laranail/package-tools

laranail/package-tools is not published to Packagist, so there is no registry-version badge to show: see Install.

Runtime base library for building Laravel packages — a fluent Package builder and an abstract PackageServiceProvider (in the spirit of spatie/laravel-package-tools), plus attribute-driven discovery, declarative + array-batch registration helpers, package-tools.* Artisan commands, abstract HTTP controllers, and a testing harness.

Requires PHP ^8.4.1 || ^8.5 on Laravel ^13.

Install

composer require laranail/package-tools

Quick start guide and usage

Getting started

Nothing to configure: package discovery registers PackageToolsServiceProvider on install, and it publishes no config of its own. Once your provider exists, verify the wiring:

php artisan about                       # your package appears in the About section
php artisan laranail::package-tools.doctor   # health-check the package wiring

Usage

Extend PackageServiceProvider and describe the package once. Configs, views, migrations and commands register themselves from that description:

use Simtabi\Laranail\Package\Tools\Package;
use Simtabi\Laranail\Package\Tools\Providers\PackageServiceProvider;

final class AcmeBlogServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('acme/blog')          // config resolves under config('acme.blog.*')
            ->hasConfigFile()
            ->hasViews()
            ->hasMigration('create_posts_table');
    }
}

Full walkthrough: docs/getting-started.md. Everything else: Documentation.

Documentation

Hosted at opensource.simtabi.com/documentation/laranail/package-tools.

Guides

• Installation — requirements and install
• Getting started — the smallest working provider
• Configuration — what the toolkit reads and how to change it
• Architecture — the Package/provider split, and why the seams are where they are
• Services — the service layer
• Seeding — db:seed-time bundles, autorun and scheduled execution
• Failure handling — classify by consequence: Critical fails fast, Degradable continues
• Release — the release process

Reference

• About sections — fluent php artisan about sections
• Action events — the PackageAction{Started,Succeeded,Failed} lifecycle events
• Attribute discovery — registering commands, routes and listeners by attribute
• Audit — the package audit command
• Command naming — the vendor::slug.command shape, and why :: needs a base class
• Command options — normalising console input, and which accessor preserves absence
• Config manager — the fluent runtime config manager
• Config namespacing — how a config key is derived, and the id-versus-key distinction
• Container — declaring singletons, facades and class aliases
• Deprecated command aliases — one-line warning when a command runs by a bare alias
• Dist integrity — every path composer.json references must survive git archive
• Doctor — health checks, and classifying them by consequence
• Http controllers — the controller base and #[AsRoute]
• Ide helper — generated IDE metadata
• Isolated testcase — the testing harness
• Driver contract — assert a driver name resolves and a config key is read where it is registered
• Logging — per-package logging via $package->log()
• Namespace forms — views and translations under both vendor/package and vendor-package
• Naming assertions — every public name scoped, asserted against the live registries
• Package registry — every package built on the toolkit, and whether two claimed one name
• Path resolver — an explicit level count instead of __DIR__ . '/../..'
• Pint — the shared code-style config
• Provider builders — force HTTPS, locale, pagination, gates, route groups, events
• Public names — why views take vendor/package:: while Blade tags cannot
• Publishing — publish tags, asset groups and orphan pruning
• Rate limiters — fluent rate limiters
• Route name aliases — deprecated bare route names that still resolve, and has() for them
• Resilience — retries, backoff and circuit breaking
• Runtime services — the services the toolkit resolves at runtime
• Sbom — provenance and SBOM generation
• Scheduling — declaring a command's cadence beside the command

Recipes

• Scaffolding a package — the smallest provider that gives you the conventions
• Adding a config file — the flat path, and the id-versus-key distinction
• Adding a command — the namespaced name and the base class it needs
• Exposing a facade — singleton, accessor and global alias in one statement
• Publishing assets — declaring the group and re-publishing on upgrade
• Adding a doctor check — asking a question a human would otherwise ask by hand
• Scheduling a command — cadence beside the command, not in the application
• Testing a package — IsolatedTestCase, and the shared-skeleton trap

Project

• Changelog
• Contributing
• Security

Contributing & security

Issues and PRs are welcome — see CONTRIBUTING.md. Report vulnerabilities per SECURITY.md (opensource@simtabi.com); participation follows the Code of Conduct.

License

MIT © Simtabi LLC. See LICENSE.