Framework Laravel Package

Getting Started

1. Confirm the environment fits before installing. Sokeio layers a module/theme/user-permission system on top of Laravel and expects a fairly modern stack (PHP 8.1+, Laravel 10/11-era conventions, Composer 2). Check the composer.json constraints in the repo against your app — this package moves fast relative to its star count, so a version mismatch is the most common first-day failure.

composer require sokeio/framework

2. Discover the actual command surface first. Everything in Sokeio is namespaced under sokeio:. Rather than guessing, list what your installed version exposes:

php artisan list | grep sokeio

You will typically find an installer, a module scaffolder, a theme scaffolder, and asset publish commands. Run the installer (usually php artisan sokeio:install) before anything else — it publishes config, registers the service provider wiring, and seeds the base permission/role tables.

3. Know where to look. After install, orient yourself in this order:

• config/sokeio.php — module paths, theme paths, admin route prefix, middleware stack, asset handling. This file is your map.
• The modules directory (commonly modules/ or app/Modules/) — each module is a self-contained Laravel mini-app.
• The themes directory — view overrides and per-theme assets.
• The package's src/ — because documentation is thin relative to the surface area, the service provider and the module manager class are the real docs. Read them early.

4. First real use case: scaffold a module, then hang a route and a permission off it. This exercises the whole stack (discovery → routing → auth) in one pass:

php artisan sokeio:module Blog

Then open the generated module's service provider / manifest, add a route, register a menu entry, and declare a permission (e.g. blog.posts.view). Log in as an admin, confirm the menu item appears, then assign the permission to a non-admin role and confirm the route is gated. If that loop works, the rest of the framework is variations on it.

Implementation Patterns

Module-as-bounded-context. Treat each Sokeio module the way you'd treat a Laravel package: its own routes, controllers, views, migrations, translations, and assets, all registered from the module's provider. Keep cross-module calls behind interfaces or events rather than reaching into another module's models. This is the single biggest lever for keeping the app maintainable, because Sokeio's discovery mechanisms don't enforce boundaries for you.

Register admin UI declaratively. The common pattern is to build the admin surface from the module provider — menu items, permissions, and settings — rather than editing a central admin file. That way installing/removing a module adds/removes its UI cleanly. Keep the registration in a dedicated method (e.g. bootAdmin()), not scattered through boot().

// inside a module service provider
public function boot(): void
{
    $this->loadRoutesFrom(__DIR__.'/routes/web.php');
    $this->loadViewsFrom(__DIR__.'/resources/views', 'blog');
    $this->loadMigrationsFrom(__DIR__.'/database/migrations');

    // menu + permission registration typically goes through
    // the framework's menu/ability registry here
}

Permission definition belongs with the module, assignment belongs with the app. Declare abilities in the module (so installing the module provisions them idempotently via a seeder or a permissions() hook), but let application seeders decide which roles get them. This keeps modules reusable across projects and avoids surprise privilege grants on install.

Theme overrides as a view-resolution layer. The usual Sokeio pattern is: module ships default views under its namespace; the active theme supplies overrides by mimicking the same view path. Practical workflow — build against the default module view, then copy only the files you need into the theme and edit there. Verify resolution by temporarily renaming the theme override and confirming the module default renders; if it doesn't, you're overriding the wrong path.

Asset handling: publish once, build per theme. Treat module public assets and theme assets as build artifacts. Put the source (SCSS/JS) in the module/theme resources/ folder, run the publish/compile step, and don't hand-edit the published copies — they will be overwritten. In CI, run the publish step as part of deploy rather than committing generated output.

Route + middleware conventions for the admin area. Keep admin routes under the framework's configured prefix and inside its admin middleware group (auth + ability checks). Write a feature test per module that hits an admin route as (a) a permitted user and (b) an unpermitted user; this catches both missing can: middleware and mis-scoped abilities, which are the two most common regressions in this kind of framework.

Localization per module. Ship module translations in the module's lang/ directory with a namespaced key. Application-level overrides go in the app's lang path so you can customize without forking the module.

Gotchas and Tips

Bus factor is the real risk here, not the API. 18 stars means few people have hit your bug before you, and documentation gaps are the norm. Mitigate concretely: pin an exact version in composer.json (not ^), commit your lockfile, and consider vendoring or forking the package into your repo for anything long-lived. Budget time for reading src/ — the framework's own service providers and module manager are the authoritative reference.

Module autoloading bites after scaffolding. New modules typically need a Composer autoload refresh before their classes resolve. If a freshly scaffolded module 500s with "class not found," the fix is almost always composer dump-autoload (and, if you changed autoload config, composer dump-autoload -o). Similarly, module discovery is often cached — after adding a module, run php artisan optimize:clear before concluding discovery is broken.

Config and route caching interact badly with dynamic registration. Because menus, permissions, and routes are registered at boot time, config:cache and route:cache can freeze a stale picture of which modules exist. During development, keep caches off; in production, rebuild caches as an explicit deploy step after modules are installed, never before. A "menu item vanished in production" bug is nearly always cache ordering.

Permission cache is a separate cache. If the underlying authorization layer caches abilities, changes made directly in the database won't take effect until that cache is flushed. Always assign permissions through the framework/API or a seeder and flush the permission cache afterward — don't UPDATE the pivot tables and expect it to work.

Migration ordering across modules is not guaranteed. Multiple modules adding migrations means ordering is by discovery, which can be surprising on a fresh install if module B's migration has a foreign key into module A's table. Either declare dependencies explicitly in the module manifest or use defensive migrations (create the referenced table only if it doesn't exist). Test a from-scratch migrate:fresh regularly — it's the fastest way to catch this.

Publish commands can silently overwrite your edits. Before running any publish command, check whether the destination already exists. Use the --force flag deliberately, never habitually. Same caution applies to themes: an asset publish can clobber custom CSS.

Views are resolved through a chain — debug by dumping the resolved path. When a theme override "doesn't apply," don't guess: log View::getFinder()->find('blog::index') or use php artisan view:cache and inspect the compiled output. Nine times out of ten the namespace or directory depth is off by one, not the theme logic.

Prefer the framework's events/hooks over patching vendor code. This class of framework typically exposes lifecycle events (module booted, theme activated, admin menu building). Hooking those is upgrade-safe; editing vendor/sokeio/framework is not. If a hook genuinely doesn't exist, write a small adapter service in your app and keep the coupling in one file.

Debugging checklist when something doesn't render or authorize: (1) php artisan list | grep sokeio — is the command even there in this version? (2) optimize:clear and composer dump-autoload; (3) php artisan route:list filtered to the prefix — is the route registered with the expected middleware? (4) check the permission cache; (5) check view resolution path. That order resolves the large majority of Sokeio issues with this package's maturity level.