Library Laravel Package

Getting Started

Read the source before you composer require it. This package has no Packagist entry, no stars, no dependents, and no visible license badge. Spend the first thirty minutes in the Bitbucket repo reading four things, in this order:

1. composer.json — PHP and illuminate/* constraints, autoload PSR-4 roots, extra.laravel.providers (the auto-discovery declaration), and whether a license key exists at all.
2. The root service provider class — this is the contract you will actually program against. Note what it registers in register() vs. boot().
3. Whatever implements the "fluent registration API" — that is the one surface you will touch every day.
4. The artisan command that publishes assets and migrations. Find its signature and its publish tags.

If there is no license file, stop and escalate. Everything below assumes the license question is resolved.

Also disambiguate the name first. "Integrated Library" in the description reads like a modularisation package (grouping service providers, config, routes), but the name is equally readable as a library-domain package (catalog, patrons, loans). The install and daily-use experience is completely different between those two. Confirm from the code, not the description, before writing any tickets.

Install from VCS, pinned. There is no Packagist resolution path, so add the repo explicitly and pin it:

{
  "repositories": [
    { "type": "vcs", "url": "[email protected]:eactive/integrated-library.git" }
  ],
  "require": {
    "integrated/library": "dev-main#<commit-sha>"
  }
}

Pin the SHA rather than tracking dev-main. Every developer machine and every CI runner then needs a Bitbucket SSH key or an app password with read scope — put that in your onboarding doc and in the CI secret rotation schedule on day one, not after the first broken build.

First use case: build one real module end to end. Resist the urge to retrofit your whole app/ into modules. Pick a small, self-contained slice — a "Reports" or "Audit" feature — and take it through the full loop:

php artisan vendor:publish --provider="Integrated\Library\LibraryServiceProvider" --tag=library

Then confirm auto-discovery actually fired:

php artisan package:discover --ansi
php artisan about

If the provider is not in the discovered list, the extra.laravel.providers key is missing or misspelled and nothing downstream will work. Fix that before writing a single module.

The success criterion for day one is narrow: one module with one route, one Blade view, one config key, and one migration, all resolving through the package's registration layer. If you cannot get that in a day, the package is not saving you time and you should say so early.

Implementation Patterns

Model every module as a vertical slice. The value proposition is that a module owns its provider, config, routes, views, translations, and migrations in one directory. Hold that line — the moment a module's controller lives in app/Http/Controllers and its view lives in resources/views, you have paid the package's complexity cost and kept none of the benefit. A module should be deletable from the filesystem with one rm -rf and one registration removal.

Use the fluent registration API as your single declaration point. The shape is roughly:

// bootstrap/providers.php or a dedicated registrar
Library::register('reports')
    ->withRoutes()
    ->withViews()
    ->withTranslations()
    ->withConfig('reports.php')
    ->withMigrations();

Confirm the method names against the source — the description gives you the capabilities, not the signatures. The important discipline is that all registration for a module goes through this one call, so the module's surface area is greppable in a single file. If a module needs a provider of its own, register it there too rather than letting it be discovered by convention; implicit discovery across two mechanisms is where debugging time goes.

Reference namespaced resources explicitly, never by guessing. Routes, views, and translations are namespaced per module, which means your call sites must be equally explicit:

Route::get('/reports/{id}', [ReportController::class, 'show'])->name('reports.show');

// Views
return view('reports::show', compact('report'));

// Translations
__('reports::messages.not_found');

Adopt one convention for the namespace segment (module key, lowercase singular) and enforce it in review. The most common day-to-day bug in packages like this is a view that resolves to the host app's resources/views/show.blade.php because the :: was dropped — and it fails silently in the form of "wrong template rendered" rather than an exception.

Keep config override layers in the right order. The package merges its defaults, the module's config file sits in the middle, and the host app's config/ wins. That means you can ship a sane default in the module and override it per environment without touching module code. Practically: never read config with env() at runtime — it returns null under config:cache, and on a modularised package this failure mode is confusing because the module's own defaults look correct until you cache.

// In module code
$limit = config('reports.page_size', 25);

Wrap the package behind your own boundary — even if you only use it internally. This is the highest-leverage pattern in this assessment. Nothing about the package suggests you should trust it with long-term ownership, so put a narrow interface in app/ and let the package satisfy it:

namespace App\Support\Modules;

interface ModuleRegistrar
{
    public function register(string $name, array $capabilities = []): void;
}

Domain and application code depends on ModuleRegistrar; one adapter class knows about Integrated\Library. That costs an hour and converts "we're stuck on an abandoned package" into a single-file swap. Do the same for any repository or lookup the package ships if it turns out to be domain-oriented.

Write contract tests against the seam, not against the package. Because there is no CI badge and no visible test suite, your tests are the only regression net you will have. Test the behaviour you depend on through your interface — module registers, route resolves, view renders, migration runs — so that a package upgrade either passes your suite or is caught in review.

Gate modules behind a flag during rollout. The package is unvetted; give yourself a kill switch per module rather than a package-wide one. A config('modules.enabled') array checked in the registrar lets you disable one misbehaving module without un-registering the package from composer.json.

Migrate incrementally, feature by feature. Do not batch-convert existing code into modules in one PR. Convert one slice, ship it, watch the logs for a week, then take the next. If you are the only consumer, this is also your exit ramp: if the package disappoints on module three, you have converted three slices, not your entire application.

Gotchas and Tips

Auto-discovery is cached, and the cache is not obvious. After adding or removing the package, package:discover runs automatically on composer install/update, but after editing a provider registration you may be staring at a stale bootstrap/cache/packages.php. When modules "randomly stop loading," run php artisan package:discover and check that file before debugging anything else.

Config and route caches break module registration differently. config:cache evaluates service providers in a different order and freezes merged config. route:cache refuses closures — if any module registers routes via a closure-based callback, production will fail where local succeeded. Test both caches in CI on every merge, not just at deploy time:

php artisan optimize && php artisan optimize:clear

Migration publishing hands you the schema. Whatever migrations the publish command emits land in your database/migrations with your timestamps. That means you own them forever, regardless of what happens upstream. Two mitigations: publish once and commit them (never re-publish over existing files), and prefix every module table (reports_, library_) so you cannot collide with application tables later. If the package assumes a specific driver — JSON columns, enum handling, full-text indexes — verify on the database you actually deploy to, not just SQLite.

Service provider ordering is load-bearing. Module providers boot after the app's providers. If a module's boot() reads a config value or binds something another module needs, the order is not guaranteed and you will see intermittent container resolution errors that vanish under --order=random-style debugging. Keep boot() to publishes(), loadViewsFrom(), and route registration. Anything else belongs behind an explicit dependency declaration.

Namespaced routes still collide on URI. Namespacing fixes route names; it does not fix overlapping paths. Two modules both registering /reports will silently shadow each other — last one wins, no warning. Adopt a URI prefix per module (/reports/..., /audit/...) and add a tiny test that asserts Route::getRoutes() contains the expected names after boot.

Translation and view namespace collisions fail quietly. loadViewsFrom() with a namespace already registered by another package overrides rather than errors. If you ever run two versions of this package in a monorepo, or a similarly-named package, you get the wrong template with no diagnostic. Namespace the module keys with your vendor prefix if there is any ambiguity.

Treat upgrades as reviewed events. Untagged VCS repos resolve to dev-main. Pin to a commit SHA, and when you bump, read the diff — there is no changelog, no advisory feed, and no dependent community to surface a broken release. Put the source URL and pinned SHA in a comment above the requirement so the next person knows why it is there.

Reach for the extension points, not the source, first. Before forking, check whether the fluent registration API accepts a custom provider or a capability array. Most registration layers of this kind are designed to be extended from the outside. Fork only when you need behaviour the registration surface cannot express — and if you do fork, name an owner, mirror it into your own SCM, and wire CI before the first custom commit lands.

Debugging checklist, in order. When a module misbehaves: (1) is the provider in bootstrap/cache/packages.php; (2) does the module appear in the registrar's registry; (3) does the view namespace resolve (view()->exists('reports::show')); (4) does the route exist (php artisan route:list --name=reports); (5) was config cached before the last edit. Those five steps cover the large majority of failures in this class of package, and running them in order is faster than reading the source again.

The honest day-to-day caveat. Zero dependents means zero externally-found bugs and zero externally-fixed ones. The package will not fail loudly the way a popular dependency does — no GitHub issue you can search, no Stack Overflow thread, no CVE feed. Budget for the reality that you are the maintainer of record for anything you build on it, and keep the internal seam described above so that when that bill comes due, paying it is a contained change rather than a rewrite.