### LinkStack Installer Routes

Source: https://context7.com/linkstackorg/linkstack/llms.txt

These routes are active only when the INSTALLING or INSTALLERLOCK file is present, guiding the initial setup of the application.

```php
// Installer routes (only active while INSTALLING or INSTALLERLOCK exists):
// GET  /             → show installer wizard view
// POST /db           → choose SQLite or MySQL
// POST /mysql        → save MySQL credentials to .env
// GET  /mysql-test   → run migrations + seeders, verify DB
// POST /create-admin → create admin user, write INSTALLERLOCK
// POST /options      → set ALLOW_REGISTRATION, REGISTER_AUTH, HOME_URL, APP_NAME
//                      delete INSTALLERLOCK → hand off to app
// POST /editConfigInstaller → write arbitrary .env key during setup
```

```bash
// Example: complete SQLite setup (automated script / curl chain)
// Step 1: choose SQLite
curl -X POST https://example.com/db -d "database=SQLite" -c cookies.txt
```

```bash
// Step 2: create admin
curl -X POST https://example.com/create-admin \
     -b cookies.txt -c cookies.txt \
     -d "_token=TOKEN&email=admin@example.com&password=secret1234&handle=admin&name=Admin"
```

```bash
// Step 3: set options
curl -X POST https://example.com/options \
     -b cookies.txt -c cookies.txt \
     -d "_token=TOKEN&register=Yes&verify=No&page=Yes&app=MyLinkStack"
```

```text
// After step 3 INSTALLING and INSTALLERLOCK are removed; app is live.
```

--------------------------------

### Installer Routes

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Endpoints available only during the initial installation process, guiding through database setup, admin creation, and initial configuration.

```APIDOC
## Installer - InstallerController

### Description
Routes for the web-based installer, active when `INSTALLING` or `INSTALLERLOCK` files are present. Guides users through database setup, admin account creation, and initial application settings.

### Endpoints

#### Show Installer Wizard
*   **Method**: GET
*   **Endpoint**: `/`
*   **Description**: Displays the main installer wizard view.

#### Select Database
*   **Method**: POST
*   **Endpoint**: `/db`
*   **Description**: Allows selection between database types, such as SQLite or MySQL.

#### Configure MySQL Credentials
*   **Method**: POST
*   **Endpoint**: `/mysql`
*   **Description**: Saves MySQL connection details to the `.env` file.

#### Test MySQL Connection
*   **Method**: GET
*   **Endpoint**: `/mysql-test`
*   **Description**: Verifies the database connection and runs migrations/seeders.

#### Create Admin User
*   **Method**: POST
*   **Endpoint**: `/create-admin`
*   **Description**: Creates the initial administrator account and writes the `INSTALLERLOCK` file.
*   **Request Body Example**:
```json
{
  "_token": "TOKEN",
  "email": "admin@example.com",
  "password": "secret1234",
  "handle": "admin",
  "name": "Admin"
}
```

#### Set Initial Options
*   **Method**: POST
*   **Endpoint**: `/options`
*   **Description**: Configures initial application settings like registration, verification, home URL, and app name. Deletes `INSTALLERLOCK` upon completion.
*   **Request Body Example**:
```json
{
  "_token": "TOKEN",
  "register": "Yes",
  "verify": "No",
  "page": "Yes",
  "app": "MyLinkStack"
}
```

#### Edit Installer Configuration
*   **Method**: POST
*   **Endpoint**: `/editConfigInstaller`
*   **Description**: Allows writing arbitrary `.env` keys during the setup process.
```

--------------------------------

### Sort Links - JavaScript Fetch Example

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Send a POST request to `/studio/sort-link` with a JSON body containing the new order of link IDs and pagination details. The response includes the status and the reordered link IDs with their new indices.

```javascript
// Route: POST /studio/sort-link
// Requires: auth middleware

// JavaScript fetch example:
fetch('/studio/sort-link', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content,
    },
    body: JSON.stringify({
        linkOrders:  [987654321, 123456789, 456789123], // IDs in new order
        currentPage: 1,
        perPage:     10,
    }),
})
.then(res => res.json())
.then(data => {
    // data.status === "OK"
    // data.linkOrders === { "987654321": 0, "123456789": 1, "456789123": 2 }
    console.log(data);
});

// Error response (bad input):
// { "status": "ERROR" }
```

--------------------------------

### Export Links - cURL Example

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Trigger the download of the authenticated user's links as a JSON file. The filename is automatically generated with the domain and current datetime. Requires authentication and `ALLOW_USER_EXPORT` to be true in `.env`.

```bash
// Route: GET /export-links
// Requires: auth middleware + ALLOW_USER_EXPORT != false in .env

// Trigger via browser navigation or curl:
// curl -b "laravel_session=..." https://example.com/export-links -o my-links.json

// Example response body (links-example.com-2024-05-01_12-00-00.json):
{
  "links": [
    {
      "id": 123456789,
      "link": "https://github.com/alice",
      "title": "My GitHub",
      "type": "predefined",
      "type_params": null,
      "order": 0,
      "click_number": 42,
      "up_link": "no",
      "user_id": 100001,
      "button_id": 45,
      "custom_css": "",
      "custom_icon": "fa-external-link",
      "created_at": "2024-01-15T09:00:00.000000Z",
      "updated_at": "2024-03-20T14:22:10.000000Z"
    }
  ]
}
```

--------------------------------

### Pull LinkStack Docker Image

Source: https://github.com/linkstackorg/linkstack/blob/main/README.md

Use this command to pull the official LinkStack Docker image. Ensure Docker is installed and running on your system.

```bash
docker pull linkstackorg/linkstack
```

--------------------------------

### Update Dependencies and Run Database Migrations

Source: https://github.com/linkstackorg/linkstack/blob/main/CONTRIBUTING.md

Run these commands in your terminal after cloning the repository to update dependencies and set up the database.

```bash
composer update -vvv

php artisan migrate
php artisan db:seed 
php artisan db:seed --class="AdminSeeder"
php artisan db:seed --class="PageSeeder"
php artisan db:seed --class="ButtonSeeder"
```

--------------------------------

### Get Footer Link Labels with footer()

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Retrieve footer link labels using footer(). It respects TITLE_FOOTER_* .env overrides.

```php
echo footer('Terms');   // "Terms of Service" (or .env TITLE_FOOTER_TERMS value)
echo footer('Privacy'); // "Privacy Policy"
echo footer('Contact'); // "Contact"
```

--------------------------------

### Locate Site Assets with findFile()

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Use findFile() to locate site assets like avatars or favicons. It returns the filename or an error string.

```php
$file = findFile('avatar');   // returns "avatar_1714000000.png" or "error.error"
$file = findFile('favicon');  // returns "favicon_1714000001.ico" or "error.error"
```

--------------------------------

### Get Block-Local Asset URL with block_asset()

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Return a URL to a block-local static asset using block_asset(). This must be called after setBlockAssetContext($typename).

```php
$cssUrl = block_asset('style.css'); // https://example.com/block-asset/myblock?asset=style.css
```

--------------------------------

### Add, Update, and Query Links - App\Models\Link

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Demonstrates adding a new link, pinning a link to the top, counting total clicks for a user, retrieving top links by clicks, and deleting a link using the App\Models\Link Eloquent model.

```php
use App\Models\Link;

// Add a new link for user 482931
$link = new Link([
    'link'      => 'https://twitter.com/alice',
    'title'     => 'Twitter',
    'button_id' => 12,   // ID of the Twitter button
    'type'      => 'predefined',
]);
$link->user_id = 482931;
$link->save();
// $link->id is a random 9-digit number e.g. 734829103

// Pin a link to the top
Link::where('id', 734829103)->update(['up_link' => 'yes']);

// Count total clicks for a user
$totalClicks = Link::where('user_id', 482931)->sum('click_number');

// Get top 5 links by clicks
$topLinks = Link::where('user_id', 482931)
    ->whereNotNull('link')->where('link', '<>', '')
    ->orderBy('click_number', 'desc')
    ->take(5)->get();

// Delete a link and its icon asset
Link::where('id', 734829103)->delete();
```

--------------------------------

### Preload Directory Files with Redis/Laravel Cache

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Scan directory files and cache them using Redis or Laravel cache with preloadDirectoryFiles().

```php
$files = preloadDirectoryFiles(base_path('assets/img'), 'assets_img_files', 3600);
// Returns array of filenames; uses Redis if available, otherwise Laravel cache
```

--------------------------------

### List, Find, and Check Link Types - App\Models\LinkType

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Shows how to list all available link types, find a specific type by its typename, and check if a link type exists using the App\Models\LinkType model. This model reads configuration from YAML files.

```php
use App\Models\LinkType;

// List all available link types
$types = LinkType::get();
foreach ($types as $type) {
    echo "{$type->typename}: {$type->title} ({$type->icon})\n";
}
// predefined: null (bi bi-boxes)
// link:       null (bi bi-link)
// vcard:      null (bi bi-person-square)
// email:      ...
// ...

// Find by typename
$emailType = LinkType::findByTypename('email');
// $emailType->typename  === 'email'
// $emailType->icon      === 'bi bi-envelope'
// $emailType->custom_html === false/true

// Check existence
if (LinkType::existsByTypename('vcard')) {
    echo "vCard blocks are available\n";
}

// A blocks/myblock/config.yml for a custom block:
// id: 10
// typename: myblock
// title: My Custom Block
// description: Embeds a custom widget
// icon: "bi bi-puzzle"
// custom_html: true
// ignore_container: false
// include_libraries: []
```

--------------------------------

### Import User Data - cURL Equivalent

Source: https://context7.com/linkstackorg/linkstack/llms.txt

This cURL command demonstrates how to import user data using a POST request, including the CSRF token and the file upload. Ensure the `import` field name matches the form input name.

```bash
// curl equivalent:
// curl -b "laravel_session=..." -X POST https://example.com/import-data \
//      -F "_token=CSRF_TOKEN" \
//      -F "import=@user_data-example.com-2024-05-01.json"
```

--------------------------------

### Find Custom Background with findBackground()

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Use findBackground() to locate a custom background image. It returns the filename or an error string.

```php
$bg = findBackground(482931); // returns "482931_1714000000.jpg" or "error.error"
```

--------------------------------

### Import User Data - Accepted JSON Structure

Source: https://context7.com/linkstackorg/linkstack/llms.txt

This is the expected JSON structure for importing user data, including profile information and links. The `links` array contains objects with details for each link to be imported. HTML in descriptions and vCard titles is sanitized, and link URLs are validated.

```json
// JSON structure accepted (export-all format):
{
  "name": "alice",
  "littlelink_description": "<p>Welcome to my page!</p>",
  "image_data": "base64encodedpngdata...",
  "image_extension": "png",
  "links": [
    { "button_id": 45, "link": "https://github.com/alice", "title": "GitHub",
      "order": 0, "click_number": 0, "up_link": "no",
      "custom_css": "", "custom_icon": "fa-external-link", "type": "predefined", "type_params": null }
  ]
}
```

--------------------------------

### Advanced Configuration File Structure

Source: https://context7.com/linkstackorg/linkstack/llms.txt

This PHP configuration file controls various aspects of the site's appearance and behavior, including SEO, custom URLs, and analytics.

```php
// config/advanced-config.php (located at storage/templates/advanced-config.php as default template)

return [
    'version'          => '2.1',        // do not change

    // SEO meta tags (applied when CUSTOM_META_TAGS=true in .env)
    'title'            => 'My Site',
    'description'      => 'All my links in one place',
    'robots'           => 'index,follow',
    'canonical_url'    => 'https://example.com/',
    'twitter_creator'  => '@alice',
    'author'           => 'Alice Smith',

    // Page title suffix on user profile pages
    'linkstack_title'  => '🔗 LinkStack',

    // Share button: "true" | "false" | "auth"
    'display_share_button' => 'true',

    // Analytics HTML injected into <head> of every page
    'analytics' => <<<EOD
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXX"></script>
<script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config','G-XXXXXXXX');</script>
EOD,

    // URL prefix: 'example.com/+alice' instead of 'example.com/@alice'
    'custom_url_prefix' => '+',

    // Custom auth route URLs
    'login_url'          => '/login',
    'register_url'       => '/register',
    'forgot_password_url'=> '/forgot-password',
    'custom_home_url'    => '/home',

    // Home page theme (folder name inside themes/)
    'home_theme' => 'galaxy',

    // Custom buttons on the home page
    'use_custom_buttons' => 'true',
    'buttons' => [
        ['button' => 'github',    'link' => 'https://github.com/alice', 'title' => 'GitHub',   'icon' => '',            'custom_css' => ''],
        ['button' => 'custom',    'link' => 'https://example.com',      'title' => 'My Site',  'icon' => 'fa-globe',    'custom_css' => 'background:#1a1a2e;color:#fff;'],
    ],
];
```

--------------------------------

### Import User Data - HTML Form

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Use this HTML form to upload a JSON file for importing user data. The `enctype` must be `multipart/form-data`. All existing links will be deleted before import. Requires authentication and `ALLOW_USER_IMPORT` to be true in `.env`.

```html
// Route: POST /import-data
// Requires: auth middleware + ALLOW_USER_IMPORT != false in .env

// HTML form:
// <form method="POST" action="/import-data" enctype="multipart/form-data">
//   @csrf
//   <input type="file" name="import" accept=".json">
//   <button type="submit">Import</button>
// </form>
```

--------------------------------

### LinkStack .env Configuration

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Configuration keys for LinkStack, controlling application name, URL, database connection, registration, mail settings, and feature flags.

```ini
# .env

APP_NAME="MyLinkStack"
APP_URL=https://example.com
APP_KEY=base64:...          # auto-generated on first run

# Database (SQLite default, no DB_HOST/PORT/DATABASE needed for SQLite)
DB_CONNECTION=sqlite        # or mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=linkstack
DB_USERNAME=dbuser
DB_PASSWORD=dbpass

# Registration & access control
ALLOW_REGISTRATION=true           # allow public sign-ups
REGISTER_AUTH=auth                # "auth" = open, "verified" = email verify required
MAX_USERS=100                     # cap total user accounts (empty = unlimited)

# Home page
HOME_URL="admin"                  # show this user's page at / (empty = marketing page)

# Maintenance
MAINTENANCE_MODE=false

# Mail (for password reset, email verification, reports)
MAIL_MAILER=smtp                  # "built-in" for PHP mail()
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=postmaster@example.com
MAIL_PASSWORD=secret
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@example.com
ADMIN_EMAIL=admin@example.com     # receives abuse reports

# Feature flags
ALLOW_USER_EXPORT=true
ALLOW_USER_IMPORT=true
FORCE_ROUTE_HTTPS=true            # forces HTTPS via URL::forceScheme

# Social login (configure per provider in config/services.php)
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_REDIRECT_URL=https://example.com/social-auth/github/callback
```

--------------------------------

### Analyze Image Brightness with analyzeImageBrightness()

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Determine if a background image is dark or light using analyzeImageBrightness(). This is used to auto-switch text color on profile pages.

```php
$tone = analyzeImageBrightness('482931_1714000000.jpg'); // "dark" | "light" | null
```

--------------------------------

### Advanced Configuration

Source: https://context7.com/linkstackorg/linkstack/llms.txt

Details on the `advanced-config.php` file, which controls various aspects of the site's appearance, SEO, and custom routing, editable via the admin panel or directly.

```APIDOC
## Advanced Configuration - config/advanced-config.php

### Description
This section details the configuration options available in the `advanced-config.php` file, which can be edited through the admin panel or by directly modifying the file. It governs SEO meta tags, custom URLs, themes, analytics, and more.

### Configuration Options

*   **`version`** (string): Specifies the configuration version. Do not change.
    *   Default: `'2.1'`

*   **SEO Meta Tags** (only applied when `CUSTOM_META_TAGS` is true in `.env`):
    *   **`title`** (string): The title for SEO meta tags.
    *   **`description`** (string): The description for SEO meta tags.
    *   **`robots`** (string): The robots meta tag value (e.g., 'index,follow').
    *   **`canonical_url`** (string): The canonical URL for the site.
    *   **`twitter_creator`** (string): The Twitter creator handle.
    *   **`author`** (string): The author's name.

*   **`linkstack_title`** (string): Suffix for page titles on user profile pages.
    *   Default: `'🔗 LinkStack'`

*   **`display_share_button`** (string): Controls the visibility of the share button. Accepts 'true', 'false', or 'auth'.
    *   Default: `'true'`

*   **`analytics`** (string): HTML snippet for injecting analytics code into the `<head>` section of every page.
    *   Example:
    ```html
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXX"></script>
    <script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config','G-XXXXXXXX');</script>
    ```

*   **`custom_url_prefix`** (string): A prefix for custom user URLs (e.g., `+` for `example.com/+alice`).
    *   Default: `'+'`

*   **Custom Auth Route URLs**:
    *   **`login_url`** (string): Custom URL for the login page.
    *   **`register_url`** (string): Custom URL for the registration page.
    *   **`forgot_password_url`** (string): Custom URL for the forgot password page.
    *   **`custom_home_url`** (string): Custom URL for the home page.

*   **`home_theme`** (string): The name of the theme folder to use for the home page.
    *   Default: `'galaxy'`

*   **`use_custom_buttons`** (string): Enables or disables custom buttons on the home page. Accepts 'true' or 'false'.
    *   Default: `'true'`

*   **`buttons`** (array): An array of custom buttons to display on the home page. Each button is an associative array with keys like `button`, `link`, `title`, `icon`, and `custom_css`.
    *   Example:
    ```php
    [
        ['button' => 'github',    'link' => 'https://github.com/alice', 'title' => 'GitHub',   'icon' => '',            'custom_css' => ''],
        ['button' => 'custom',    'link' => 'https://example.com',      'title' => 'My Site',  'icon' => 'fa-globe',    'custom_css' => 'background:#1a1a2e;color:#fff;'],
    ]
    ```
```