Base Laravel Package

Getting Started

Treat your first hour with tonycms/base as source reconnaissance, not integration. There is no meaningful upstream documentation, so the vendored source is the documentation.

1. Pull it in and see what it actually ships:

   composer require tonycms/base
   ls -R vendor/tonycms/base | head -80
   cat vendor/tonycms/base/composer.json
   

   Check extra.laravel.providers for auto-discovery and autoload.psr-4 for the real namespace. The repo is named TonyCMS/Base but the package is tonycms/base — confirm the casing resolves before you write a single use statement.

2. Read in this order:

   • README.md — usually the only doc.
   • src/Providers/*ServiceProvider.php — register() tells you what's bound, boot() tells you what's loaded (routes, migrations, config, commands, views).
   • config/*.php after php artisan vendor:publish — this is your real feature surface.
   • database/migrations/ — base tables the module expects to exist.

3. Prove the primitives boot before trusting them:

   php artisan about
   php artisan route:list | head -40
   php artisan migrate --pretend
   

   If routes and migrations resolve cleanly, you have something to build on. Then extend one base class or contract inside app/ to verify the extension path works — do this before committing any domain code to the package's abstractions.

4. First real use case. A "base module" normally provides scaffolding: base models/repositories, shared middleware, module registration, and helper utilities. Day-to-day, you will spend most of your time extending it rather than using it — so the first productive task is usually creating App\Models\BaseModel extends \TonyCms\Base\Models\BaseModel (or the equivalent) and getting one domain model through it end-to-end.

Implementation Patterns

Treat it as infrastructure, not a feature dependency. It pays off only if your code depends on its abstractions and those abstractions rarely change. Everything below follows from that.

• Never edit vendor/. Use config, subclassing in app/, or rebinding contracts in your own service provider. If the package binds an interface in register(), rebind after the package provider boots:

  // App\Providers\AppServiceProvider::register()
  $this->app->bind(
      \TonyCms\Base\Contracts\Something::class,
      \App\Base\CustomSomething::class
  );
  

• Wrap the base classes once. Instead of class Post extends \TonyCms\Base\Models\BaseModel, create App\Models\BaseModel extends \TonyCms\Base\Models\BaseModel and have every domain model extend yours. That single seam lets you absorb upstream changes or drop the package entirely without touching business code.

• Config is the integration contract. Published config files are the stable extension point. Anything you can set there is supported; anything you reach for via reflection is not. Keep overrides in config/ and environment-driven values in .env under a TONYCMS_-style prefix so deploy config stays greppable.

• Follow the package's module registration path. If it offers module discovery, register your feature modules through it rather than adding bespoke service providers alongside — otherwise you end up with two bootstrapping systems and non-obvious load order.

• Sequence migrations, don't fork them. If the base module owns a table and you need an extra column, add a new migration in database/migrations/ that alters it. Never copy the vendor migration into your project — migrate:fresh becomes non-deterministic across environments the moment timestamps diverge.

• Build a smoke-test suite on day one. With no upstream tests you can rely on, your own are the regression net:

  public function test_base_module_boots(): void
  {
      $this->assertTrue($this->app->bound(\TonyCms\Base\Contracts\Something::class));
  }
  

  Add a test that hits one published route and one base-table migration. Those three tests will catch 80% of "the package silently broke" scenarios when you bump Laravel or PHP.

• Pin and vendor. Use an exact tag or commit in composer.json, and consider composer vendor-dir isolation or a forked repo under your org. For a package with no release cadence, "latest" is a moving target you don't control.

Gotchas and Tips

• Supply-chain risk is the headline issue. Zero stars, zero dependents, minimal description means no community validation and effectively no bus factor. Fork or vendor before production; do not rely on Packagist availability for a rebuild.

• Service provider boot order. If the base module's boot() assumes routes/config are already loaded, a late-registered provider of yours can win the race silently. Check config/app.php order and prefer register() (binding) over boot() (side effects) in your own code where possible.

• Hidden global behavior. Base modules often ship helper functions, facades, and macros that autoload everywhere. Grep src/ for function at file scope and for Macroable/::macro( calls — these are the things that will surprise you in tests and in queue workers.

• Debugging a failing boot. If php artisan throws after install, wrap the provider registration to isolate the cause:

  php artisan list -vvv
  

  Then comment out your own providers in config/app.php and re-run. If the package still fails to boot, the problem is upstream and you need to read register() line by line.

• Route and middleware collisions. php artisan route:list after install — check for names or prefixes that clash with your app. Base modules frequently register admin routes eagerly; remove or disable them via config rather than deleting the provider.

• Auth and user-model assumptions are the most likely hard failure. If the base module assumes App\Models\User, a users table shape, or a specific guard, isolate that behind your own adapter or you'll fight it forever in custom-auth apps.

• Config merge quirks. mergeConfigFrom() is shallow — nested arrays from the package override yours entirely unless the package uses mergeConfigFrom with deep merge or you re-declare the whole tree. Verify by dd(config('tonycms')) after publish.

• Extension points to prefer, in order: published config → published migrations → subclassing base classes → rebinding contracts in your own provider → forking. Anything below "rebinding" is a maintenance tax you should account for upfront.

• Exit plan. Because you will likely own this code, keep a docs/tonycms-adapter.md in your repo listing every class and config key you depend on. That one page is what makes "replace or fork" a weekend rather than a quarter if upstream goes quiet.