Laraship Laravel Package

Getting Started

Laraship is distributed as an application skeleton, not a drop-in library. The fastest start is the skeleton install rather than composer require into an existing app:

composer create-project corals/laraship my-app
cd my-app
cp .env.example .env
php artisan key:generate
# configure DB in .env, then:
php artisan migrate
php artisan db:seed
php artisan serve

Where to look first, in order:

1. modules/ — the heart of the platform. Each business capability (users, roles, settings, media, blog, etc.) is a self-contained module with its own controllers, models, routes, views, migrations, and service provider. Read one small module end-to-end before writing anything.
2. config/ — platform-level config for modules, themes, and settings. This is where feature toggles and module registration live.
3. themes/ (or the theme path referenced in config) — front-end views are layered over module views; knowing the override order prevents a lot of confusion.
4. Admin routes — log in as the seeded admin and walk the admin panel; it's the clearest map of what ships out of the box.

First real use case: pick a trivial entity (e.g., Project or Ticket), scaffold a module for it, and wire it into the admin nav. That single exercise touches routing, permissions, migrations, views, and the settings system — the four things you'll do every day.

Implementation Patterns

Module-oriented development. Treat every feature as a module. A typical module layout:

modules/Projects/
  Controllers/
  Models/
  Requests/
  Routes/web.php        (and api.php where applicable)
  Views/
  Migrations/
  Providers/ProjectsServiceProvider.php
  module.json           (or equivalent registration metadata)

Register the provider in config/app.php (or the platform's module registry — check how existing modules do it), then composer dump-autoload if the module uses its own namespace.

Scaffold-then-refine. The platform's CRUD/module generator gives you a working controller, model, migration, request validation, and admin views. Use it to get the boring 80% and then edit by hand. Don't hand-roll what the generator produces unless you have a strong reason.

Permissions as a first-class concern. New admin screens should be gated with the platform's role/permission system, not ad-hoc middleware. Define permission keys alongside the module and assign them to roles in a seeder so fresh installs and CI environments behave identically.

Settings over hardcoding. Site name, mail config, feature flags, and per-module options are typically stored through the settings service and cached. Read them via the helper/service rather than config() so admin edits take effect without a deploy.

Theme-aware views. When you need to customize a front-end screen, override the view in the active theme instead of editing module views. This keeps upgrades clean — module updates won't clobber your customizations.

Events and hooks for cross-module work. Modules shouldn't reach into each other directly. Fire an event from module A and listen in module B (registered in B's service provider). This is the difference between a maintainable platform and a ball of mud six months in.

Typical day-to-day loop:

php artisan make:module Invoice       # or the platform's scaffold command
php artisan migrate
php artisan module:enable Invoice      # name varies — confirm from existing modules
php artisan optimize:clear

Then iterate on controller → request → view, seed permissions, and add a menu entry.

Gotchas and Tips

• It's an app, not a package. Do not try to composer require corals/laraship inside an existing Laravel project and expect it to graft on. It owns app/, routing conventions, the admin panel, and the module loader. Adopt it as the base or not at all.
• License matters for commercial work. GPL-3.0 is copyleft. If you're shipping a closed-source SaaS or product, get legal input before building on it — this is the single biggest practical blocker for startups evaluating Laraship.
• Small community, thin public docs. With ~74 stars and zero dependents, expect to learn primarily by reading the source of shipped modules. Budget extra time for discovery; don't expect Stack Overflow answers. The vendor site's docs are usually more current than the repo README.
• Laravel version pinning. The skeleton pins a specific Laravel major. Upgrading Laravel independently of the platform can break module internals. Upgrade Laraship first, then reconcile your custom modules.
• Cache is the usual culprit. After adding a module, route, view, or permission, run php artisan optimize:clear (and any module-specific cache clear). Stale route/config/settings caches cause the majority of "my new module doesn't appear" bugs.
• Autoloading for custom modules. If a new module's classes aren't found, it's almost always a missing PSR-4 entry or a stale composer dump-autoload. Check the module's composer.json/namespace against the directory name.
• Migrations are per-module and ordered. Don't edit shipped migrations; add new ones. If a module migration fails midway, fix forward with a new migration rather than rolling back into platform tables.
• Permission and settings caches. New permission keys often won't show in the admin UI until the permission cache is refreshed (or the seeder re-run). Same for settings — write through the settings service, not directly to the DB.
• View override precedence. If your theme change "doesn't apply," you're likely editing the module view while the theme override wins. Trace which path actually renders (check the compiled view path or temporarily break the file).
• Route collisions. Modules register their own route files; a broad wildcard in one module can shadow another's admin routes. Namespace and prefix consistently, and check php artisan route:list when a 404 appears out of nowhere.
• Extension points to prefer: module service providers, the event/listener system, view composers, and theme overrides. Avoid editing vendor/platform core — patching core is the fastest way to make future upgrades painful.
• Vendor lock-in reality check. Because it's a full platform with its own conventions, migrating off later is non-trivial. Prototype the riskiest requirement (auth flows, multi-tenancy, payments) in a spike before committing the team.