package-dev Skill: Автоматизация разработки Laravel пакетов

--- name: package-dev metadata: compatible_agents: [claude-code] tags: [laravel, php, package, sdk, composer, packagist] description: > Complete Laravel package development skill — scaffolds package directory structure with src, config, migrations, tests, README, and CHANGELOG; generates service providers, facades, config publishing patterns; sets up Pest test suites with Orchestra Testbench integration; manages release workflows including version bumps, changelog updates, git tags, and Packagist publishing; generates professional README files with badges, installation instructions, usage examples, testing commands, and changelog sections. Use this skill whenever the user asks to create a Laravel package, scaffold a PHP package, set up a Composer library, generate a service provider, add facade support, configure Testbench tests, prepare a package release, write a package README, publish to Packagist, or manage package versioning — including: "create a new Laravel package", "scaffold package structure", "set up package tests", "prepare a release", "generate package README", "add a facade to my package", "configure Testbench", "publish my package", "buat package Laravel baru", "scaffold struktur package", "sediakan test untuk package", "sediakan release", "jana README package", "tambah facade", "konfigurasi Testbench", "terbitkan package ke Packagist", "uruskan versioning package", "upgrade Laravel version", "bump PHP version constraint", "update package dependencies", "naik taraf versi Laravel", "kemaskini versi PHP", or "upgrade dependencies package". --- # Package Development Skill Scaffold, test, document, and release production-quality Laravel/PHP packages — from initial directory structure through Packagist publishing. Follows Laravel ecosystem conventions and integrates with Orchestra Testbench for package testing. ## Command Reference | Command | Description | |---|---| | `/package scaffold` | Generate complete package directory structure with all boilerplate files | | `/package test` | Set up Pest test suite with Orchestra Testbench integration | | `/package release` | Run release checklist: version bump, changelog, git tag, Packagist | | `/package readme` | Generate professional README with badges, installation, usage, and testing sections | | `/package upgrade` | Upgrade PHP/Laravel version constraints and dependencies | --- ## 1. `/package scaffold` — Generate Package Structure ### Step 1: Gather Package Information Ask the user for: - **Vendor name** — always ask, default: `cleaniquecoders` - **Package name** — kebab-case, all lowercase (e.g. `laravel-helper`, `profile`) - **Package type** — Laravel package or pure PHP package - **Package description** (one-liner for composer.json) - **PHP minimum version** (default: `^8.4`) - **Laravel version constraint** (default: `^12.0`, Laravel packages only) - **Namespace** (default: derived from vendor/package, e.g. `CleaniqueCodersProfile`) - **Features to include** (config, migrations, views, routes, commands — pick applicable ones) If the user already provided context, extract what you can and only ask for what is missing. ### Skeleton Templates Use Spatie's skeleton templates to scaffold the package: - **Laravel package**: Clone from [spatie/package-skeleton-laravel](https://github.com/spatie/package-skeleton-laravel) - **PHP package**: Clone from [spatie/package-skeleton-php](https://github.com/spatie/package-skeleton-php) After cloning, run the skeleton's configure script to replace placeholders with the actual vendor name, package name, namespace, and author details. ### Step 2: Generate Directory Structure Create the following structure: ``` packages/vendor/package-name/ ├── src/ │ ├── PackageNameServiceProvider.php │ ├── Facades/ │ │ └── PackageName.php │ ├── Actions/ │ ├── Concerns/ │ └── Contracts/ ├── config/ │ └── package-name.php ├── database/ │ ├── factories/ │ └── migrations/ ├── resources/ │ └── views/ ├── routes/ │ └── web.php ├── tests/ │ ├── Pest.php │ ├── TestCase.php │ └── Feature/ ├── stubs/ ├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── composer.json └── phpunit.xml ``` Only include directories for features the user selected. Always include `src/`, `tests/`, `composer.json`, `README.md`, `CHANGELOG.md`, and `LICENSE`. ### Step 3: Generate composer.json Read `references/package-structure.md` for the full template. Key sections: ```json { "name": "vendor/package-name", "description": "Package description here", "keywords": ["laravel", "php"], "license": "MIT", "require": { "php": "^8.4", "illuminate/support": "^12.0" }, "require-dev": { "orchestra/testbench": "^10.0", "pestphp/pest": "^3.0", "pestphp/pest-plugin-laravel": "^3.0", "laravel/pint": "^1.0" }, "autoload": { "psr-4": { "Vendor\PackageName\": "src/" } }, "autoload-dev": { "psr-4": { "Vendor\PackageName\Tests\": "tests/" } }, "extra": { "laravel": { "providers": [ "Vendor\PackageName\PackageNameServiceProvider" ], "aliases": { "PackageName": "Vendor\PackageName\Facades\PackageName" } } }, "config": { "sort-packages": true, "allow-plugins": { "pestphp/pest-plugin": true } }, "minimum-stability": "dev", "prefer-stable": true } ``` ### Step 4: Generate ServiceProvider Read `references/package-structure.md` for the full ServiceProvider patterns. The provider must: - Extend `IlluminateSupportServiceProvider` - Use `register()` for bindings and merging config - Use `boot()` for publishing assets, loading routes, views, migrations, and commands - Include conditional `if ($this->app->runningInConsole())` blocks for publishable assets - Group publishes with tags: `{package-name}-config`, `{package-name}-migrations`, etc. ### Step 5: Generate Facade ```php <?php declare(strict_types=1); namespace VendorPackageNameFacades; use IlluminateSupportFacadesFacade; /** * @see VendorPackageNamePackageName */ class PackageName extends Facade { protected static function getFacadeAccessor(): string { return VendorPackageNamePackageName::class; } } ``` ### Step 6: Generate Config File ```php <?php return [ // Package configuration options ]; ``` ### Step 7: Generate Starter Files Generate `.gitignore`, `LICENSE` (MIT), initial `CHANGELOG.md`, and `phpunit.xml`. --- ## 2. `/package test` — Pest + Orchestra Testbench Setup ### Step 1: Check Existing Test Setup Scan the package for existing `tests/` directory and `phpunit.xml`. If they exist, extend rather than overwrite. ### Step 2: Generate TestCase Base Class Read `references/testbench-patterns.md` for the full Testbench TestCase patterns. ```php <?php declare(strict_types=1); namespace VendorPackageNameTests; use OrchestraTestbenchTestCase as Orchestra; use VendorPackageNamePackageNameServiceProvider; class TestCase extends Orchestra { protected function setUp(): void { parent::setUp(); } protected function getPackageProviders($app): array { return [ PackageNameServiceProvider::class, ]; } protected function getPackageAliases($app): array { return [ 'PackageName' => VendorPackageNameFacadesPackageName::class, ]; } protected function getEnvironmentSetUp($app): void { config()->set('database.default', 'testing'); config()->set('database.connections.testing', [ 'driver' => 'sqlite', 'database' => ':memory:', 'prefix' => '', ]); } protected function defineDatabaseMigrations(): void { $this->loadMigrationsFrom(__DIR__ . '/../database/migrations'); } } ``` ### Step 3: Generate Pest.php ```php <?php declare(strict_types=1); use VendorPackageNameTestsTestCase; uses(TestCase::class)->in('Feature'); ``` ### Step 4: Generate Starter Tests Generate tests based on what the package provides: | Package Feature | Test File | Key Assertions | |---|---|---| | ServiceProvider | `tests/Feature/ServiceProviderTest.php` | Provider loads, bindings resolve, config merges | | Config | `tests/Feature/ConfigTest.php` | Config file publishable, default values correct | | Migrations | `tests/Feature/MigrationTest.php` | Tables created, columns match expectations | | Commands | `tests/Feature/CommandTest.php` | Command registered, executes without error | | Routes | `tests/Feature/RouteTest.php` | Routes registered, middleware applied, responses correct | | Facade | `tests/Feature/FacadeTest.php` | Facade resolves, methods callable | ### Step 5: Generate phpunit.xml ```xml <?xml version="1.0" encoding="UTF-8"?> <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd" bootstrap="vendor/autoload.php" colors="true" > <testsuites> <testsuite name="Feature"> <directory>tests/Feature</directory> </testsuite> </testsuites> <source> <include> <directory>src</directory> </include> </source> </phpunit> ``` --- ## 3. `/package release` — Release Checklist ### Step 1: Pre-Release Validation Run through these checks before releasing: | Check | Command | Pass Condition | |---|---|---| | Tests pass | `composer test` or `./vendor/bin/pest` | Exit code 0, no failures | | Code style | `./vendor/bin/pint --test` | No style violations | | No uncommitted changes | `git status` | Clean working tree | | README up to date | Manual review | Installation, usage, and changelog sections current | | License file present | `ls LICENSE` | File exists | ### Step 2: Version Bump Follow Semantic Versioning (SemVer): | Change Type | Version Bump | Example | |---|---|---| | Bug fix, patch | PATCH | `1.0.0` -> `1.0.1` | | New feature, backward-compatible | MINOR | `1.0.1` -> `1.1.0` | | Breaking change | MAJOR | `1.1.0` -> `2.0.0` | Update the version in `composer.json` if a `version` field exists (most packages rely on git tags instead). ### Step 3: Update CHANGELOG.md Follow Keep a Changelog format: ```markdown # Changelog All notable changes to this project will be documented in this file. ## [Unreleased] ## [1.1.0] - 2026-02-27 ### Added - New feature X for handling Y - Support for Laravel 12 ### Changed - Updated minimum PHP version to 8.2 ### Fixed - Resolved issue with config publishing (#42) ## [1.0.0] - 2026-01-15 ### Added - Initial release - Service provider with config publishing - Facade support - Migration publishing [Unreleased]: https://github.com/vendor/package/compare/1.1.0...HEAD [1.1.0]: https://github.com/vendor/package/compare/1.0.0...1.1.0 [1.0.0]: https://github.com/vendor/package/releases/tag/1.0.0 ``` ### Step 4: Commit and Tag ```bash git add -A git commit -m "chore: release 1.1.0" git tag -a 1.1.0 -m "1.1.0" git push origin main --tags ``` ### Step 5: Packagist Publishing - **First release:** Register at [packagist.org](https://packagist.org/packages/submit) with the GitHub repository URL - **Subsequent releases:** Packagist auto-updates if the GitHub webhook is configured; otherwise run `curl -X POST https://packagist.org/api/update-package?username=USER&apiToken=TOKEN` - Verify the release appears on Packagist within a few minutes --- ## 4. `/package readme` — README Generation ### Step 1: Scan Package Read `composer.json`, `src/`, and `config/` to understand what the package provides. ### Step 2: Generate README Structure ```markdown # Package Name [](https://packagist.org/packages/vendor/package-name) [](https://github.com/vendor/package-name/actions?query=workflow%3Arun-tests+branch%3Amain) [](https://packagist.org/packages/vendor/package-name) Short description of the package — one or two sentences. ## Installation You can install the package via Composer: ```bash composer require vendor/package-name ``` You can publish the config file with: ```bash php artisan vendor:publish --tag="package-name-config" ``` Optionally, you can publish the migrations with: ```bash php artisan vendor:publish --tag="package-name-migrations" ``` ## Usage ```php use VendorPackageNameFacadesPackageName; // Example usage $result = PackageName::doSomething(); ``` ## Testing ```bash composer test ``` ## Changelog Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. ## Contributing Please see [CONTRIBUTING](CONTRIBUTING.md) for details. ## Security Vulnerabilities Please review [our security policy](../../security/policy) on how to report security vulnerabilities. ## Credits - [Author Name](https://github.com/author) - [All Contributors](../../contributors) ## License The MIT License (MIT). Please see [License File](LICENSE) for more information. ``` ### Step 3: Customise Sections Based on the package scan: | Package Feature | README Section to Add | |---|---| | Config file | "Configuration" section with key options documented | | Migrations | "Database" section explaining tables created | | Commands | "Commands" section listing artisan commands | | Routes | "Routes" section with endpoint table | | Views | "Views" section explaining publishable views | | Events | "Events" section listing dispatched events | | Middleware | "Middleware" section with registration instructions | --- ## 5. `/package upgrade` — Upgrade Dependencies Bump PHP, Laravel, and ecosystem dependency version constraints in an existing package. ### Step 1: Read Current State Parse `composer.json` for current constraints: - `require.php` - All `illuminate/*` packages - `orchestra/testbench` - `pestphp/pest-plugin-laravel` - `laravel/pint` - Any other Laravel-ecosystem dependencies ### Step 2: Check Dependency Availability For each dependency being upgraded, verify the target version exists on Packagist: - Use `composer show {package} --available` or check `https://packagist.org/packages/{vendor}/{package}` to confirm the target version/constraint is published - Flag any dependency that does not yet have a compatible release for the target Laravel/PHP version - If a dependency is not available, warn the user and suggest alternatives: wait for the release, find a fork, or drop the dependency ### Step 3: Show Current vs Target Display a comparison table with availability status: | Dependency | Current | Target | Available? | |---|---|---|---| | `php` | `^8.2` | `^8.4` | ✅ | | `illuminate/support` | `^11.0` | `^12.0` | ✅ | | `orchestra/testbench` | `^9.0` | `^10.0` | ✅ | | `pestphp/pest-plugin-laravel` | `^2.0` | `^3.0` | ✅ | ### Step 4: Ask Target Versions Confirm with the user before proceeding. Defaults: - **PHP**: `^8.4` - **Laravel**: `^12.0` - **Testbench**: `^10.0` ### Step 5: Reference Upgrade Guide Point the user to the official Laravel upgrade guide for breaking changes: - `https://laravel.com/docs/{targetMajor}.x/upgrade` For example, when upgrading to Laravel 12: `https://laravel.com/docs/12.x/upgrade` ### Step 6: Update composer.json Bump version constraints for: - `require.php` - All `illuminate/*` packages in `require` and `require-dev` - `orchestra/testbench` - `pestphp/pest-plugin-laravel` - `laravel/pint` - Any other Laravel-ecosystem dev dependencies ### Step 7: Run Composer Update ```bash composer update ``` If dependency resolution fails, report which packages conflict and suggest resolution steps. ### Step 8: Run Tests ```bash composer test ``` Or `./vendor/bin/pest` if no `test` script is defined. Report any failures so the user can address breaking changes. ### Step 9: Update README If the README contains version badges or a "Requirements" section referencing specific PHP/Laravel versions, update those to match the new constraints. ### Version Compatibility Matrix | Laravel | PHP | Testbench | Pest Plugin Laravel | |---------|----------|-----------|---------------------| | 12.x | ^8.2 | ^10.0 | ^3.0 | | 11.x | ^8.2 | ^9.0 | ^2.0 / ^3.0 | | 10.x | ^8.1 | ^8.0 | ^2.0 | --- ## 6. Anti-Patterns to Avoid | Anti-Pattern | Correct Approach | |---|---| | Hardcoding Laravel version in ServiceProvider | Use `illuminate/*` packages with version ranges | | Registering everything in `boot()` | Use `register()` for bindings, `boot()` for bootstrapping | | Missing `declare(strict_types=1)` | Include in every PHP file | | No publish tags | Always tag publishable assets: `{package}-config`, `{package}-migrations` | | Monolithic ServiceProvider | Extract to separate concerns if provider exceeds 100 lines | | Testing against real database | Always use SQLite `:memory:` via Testbench | | Missing `extra.laravel` in composer.json | Required for auto-discovery to work | | No `.gitignore` for `vendor/` and `composer.lock` | Packages must ignore `composer.lock` (apps keep it) | --- ## Reference Files | File | Read When | |---|---| | `references/package-structure.md` | Scaffolding package structure, ServiceProvider, Facade, and composer.json patterns | | `references/testbench-patterns.md` | Setting up Orchestra Testbench, writing package tests |