README

Runtime base library for building Laravel packages.

A fluent Package builder and an abstract PackageServiceProvider your package extends, in the spirit of spatie/laravel-package-tools. On top of that base it adds attribute-driven discovery, a set of package-tools.* Artisan commands, abstract HTTP controllers, and a testing harness.

Status: v0.1.0, the first public release.

Contents

• Requirements
• Installation
• Quick start
• What you get
• Artisan commands
• Attribute discovery
• Documentation
• Local development
• Provenance
• Sister packages
• Contributing & security
• License

Requirements

• PHP ^8.3 (8.3, 8.4 and 8.5 are supported; CI tests the full 8.3 / 8.4 / 8.5 matrix)
• Laravel ^13.0
• For development: Pest ^3.0, Testbench ^11.0, Larastan ^3.0

Installation

composer require laranail/package-tools

The service provider is auto-discovered, so the package-tools.* commands are available as soon as the package is installed.

Quick start

Extend PackageServiceProvider and describe your package in configurePackage():

use Simtabi\Laranail\PackageTools\Package;
use Simtabi\Laranail\PackageTools\PackageServiceProvider;

final class FooServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('vendor/foo')
            ->hasConfigFile()
            ->hasViews()
            ->hasMigration('create_foos_table')
            ->hasInstallCommand(fn ($command) => $command
                ->publishConfigFile()
                ->askToRunMigrations())
            ->discoversWithAttributes()
            ->hasDoctorCheck(FooHealthCheck::class);
    }
}

A complete, runnable example lives in docs/examples/.

What you get

The full reference is in docs/ — see Documentation.

Artisan commands

Registered automatically via package auto-discovery.

Commands follow the laranail::<package-slug>.<command> naming used across the laranail family (the :: separator is enabled by the package's base command — see CONTRIBUTING.md).

Attribute discovery

use Simtabi\Laranail\PackageTools\Attributes\AsArtisanCommand;
use Simtabi\Laranail\PackageTools\Attributes\AsRoute;
use Simtabi\Laranail\PackageTools\Attributes\AsViewComposer;
use Simtabi\Laranail\PackageTools\Attributes\AsFacade;

#[AsArtisanCommand(signature: 'foo:run', description: 'Run the foo task')]
class FooCommand extends Command {}

#[AsRoute(method: 'GET', uri: '/foo')]
#[AsRoute(method: 'POST', uri: '/foo', name: 'foo.create', middleware: ['web'])]
class FooController {}

#[AsViewComposer(views: ['layouts.app', 'partials.header'])]
class AppViewComposer {}

See docs/tools/attribute-discovery.md.

Documentation

Hosted at opensource.simtabi.com/package-tools/docs/ (product page: opensource.simtabi.com/package-tools/). The same pages live under docs/:

Guides

• Installation — requirements, install, auto-registration
• Configuration — the fluent Package builder and lifecycle hooks
• Architecture — how the runtime is put together
• Services reference — the service and support classes

Tools & features

• package-tools.doctor — health checks
• package-tools.sbom — CycloneDX SBOM
• package-tools.audit — OSV.dev advisory scan
• package-tools.ide-helper — Facade generation from #[AsFacade]
• Attribute discovery — #[AsArtisanCommand], #[AsRoute], #[AsViewComposer]
• Command naming — the laranail::<slug>.<command> separator, the base Command, and SupportsNamespacedNames
• HTTP controllers — WebController and ApiController
• IsolatedTestCase — the testing harness
• Runtime services — SystemService, HttpConfigurationService, ErrorStorageService

Examples

• Runnable examples — a cohesive Acme\Hello package that demonstrates every feature end to end: the fluent builder and lifecycle hooks, all four discovery attributes, namespaced commands, the WebController/ApiController bases, doctor checks, the runtime services and consumer traits, package seeders, the install-command flow, and an IsolatedTestCase test

Local development

bash .scripts/init.sh   # verify PHP >= 8.3, run composer install, smoke-check
composer setup          # alias for .scripts/init.sh
composer test           # run the Pest suite
composer test-coverage  # run with coverage
composer lint           # Pint + PHPStan + Rector (dry run)
composer pint-fix       # apply Pint formatting
composer rector-fix     # apply Rector transformations
composer audit          # composer security audit

.scripts/init.sh is the only shell script in the repo; everything else runs through Composer.

Provenance

The open API surface (hasConfigFile(), hasViews(), the lifecycle hooks, and friends) is intentionally compatible with spatie/laravel-package-tools (MIT). Code is copyright Simtabi LLC; see LICENSE.

Sister packages

• laranail/package-scaffolder — Artisan generator that scaffolds new packages on top of package-tools.
• laranail/database-tools — standalone Laravel database utilities; no dependency on package-tools.
• laranail/laranail — Simtabi's Laravel utility toolbox.

Contributing & security

• CONTRIBUTING.md — workflow, coding standards, command naming.
• SECURITY.md — how to report a vulnerability.
• CODE_OF_CONDUCT.md — community expectations.
• CHANGELOG.md — release history.

License

MIT. See LICENSE.