# Installation
Follow these steps to integrate Laravel K Framework into your project:

Why this matters: installation publishes the framework's config, assets, and database tables, so the `<x-kfw::assets />` header component is available in every view.


1. **Install via Composer**  
   Run the following command in your terminal to install the package:
   ```bash
   composer require northumber/laravel-k-framework
   ```

2. **Publishing assets and configs**  

    Ensure to run the command every time the K-Framework is installed or updated:
    
    ```bash
    php artisan kfw:update
    ```
   
    This will automatically, in order:
    - Run all the migrations — runs `migrate` to create/update `kfw_*` tables (roles, users profile, API credentials, notifications).
    - Publish assets and configs (`kfw:publish`) — removes legacy `public/vendor/k-framework/css/` + `js/` folders, copies framework CSS/JS, fonts, and themes to `public/vendor/k-framework` (forced overwrite) so the browser bundle is up to date, and copies `src/config/*.php` to `config/k-framework` on first install (without force, so your local edits are preserved). It also renews the client assets cache (`kfw:refresh-assets`: bumps `kfwAssetsVersion`, recompiles `kfw_assets.js` / `kfw_assets.css`, forces browsers to download the new bundle).
    - Merge new config keys (`kfw:configs-update`) — adds keys introduced by the update while preserving your local values (`navigation.php` is managed separately).
    - Rebuild optimization caches (`optimize`) — freezes config/routes including the registered resources, so `/resources/*` routes are available from cache. `kfw:update` registers framework + app (`app/Resources/*`) resources this way; running `php artisan optimize` alone does the same registration into the route cache.

    All framework configs live in `config/k-framework` after this step.

    Re-run `php artisan kfw:update` every time you `composer install` / `composer update` the package, deploy to a new environment, or pull a version with new config keys, assets, or migrations. It is safe to re-run: configs merge missing keys without overwriting your values (except `navigation.php`, which is managed separately), assets are recompiled, and migrations are idempotent.

    If framework tables or `kfw_*` indices are out of sync and `migrate` reports nothing to run, enforce them with `php artisan kfw:remigrate` (see [Framework remigrate](usage/utilities/backend/kfw_remigrate.md)). The command asks for confirmation because re-running migrations may cause data loss; use `--force` only in non-interactive scripts.


#### All done!

3. **(Optional) Adding the command to the composer**

    You can add to the composer the command above, so every time the package is updated (or installed) it will run automatically:
    
    ```json
    {
        "scripts": {
            "post-install-cmd": [
                "@php artisan kfw:update"
            ],
            "post-update-cmd": [
                "@php artisan kfw:update"
            ]
        }
    }
    ```

    Verify the install worked (why this matters: missing assets = unstyled pages, missing config = wrong theme/behavior):

    ```bash
    ls config/k-framework
    ls public/vendor/k-framework
    php artisan migrate:status | grep kfw
    ```

    You should see `config/k-framework/ui.php`, `api.php`, `roles.php` and friends, plus `public/vendor/k-framework/kfw_assets.js`, `kfw_assets.css`, `kfw_boot.js`, and `fonts/` / `themes/` / `custom-css/` / `custom-js/`.

    Minimal end-to-end check after install — build the component in controller and echo it in Blade:

    Build in controller:

    ```php
    use KFramework\Components\Visual\Alert;

    public function index()
    {
        $hello = Alert::make()->setContent('Install OK!');

        return view('home', compact('hello'));
    }
    ```

    Echo in Blade:

    ```php
    <x-kfw::assets />
    {!! $hello !!}
    {!! \KFramework\Components\Visual\Alert::make()->setContent('Install OK!') !!}
    ```

    **See also / Next steps:** for layout integration see [UI basics and config](usage/styling/basics.md) (base `<x-kfw::ui>` vs custom `<x-kfw::assets />` implementation), then continue with [Usage](usage.md) and [Dependencies](dependencies.md).