Pentacraft Laravel Package

Getting Started

1. Read the README first. The package is documented in Portuguese (Brazilian Laravel ecosystem), so budget a few minutes for translation. The README is the authoritative source for the artisan command names and configuration keys.
2. Install via Composer:

   composer require alexandresafarpaim/pentacraft
   

   Pin the version ("alexandresafarpaim/pentacraft": "^x.y") — with a small maintainer base you want reproducible installs.
3. Publish configuration / stubs (check the README for the exact tag):

   php artisan vendor:publish --provider="Alexandresafarpaim\Pentacraft\PentacraftServiceProvider"
   

   Review the published config to see which namespaces, route files, and base classes the generators target.
4. Where to look in the source (after composer require):
   • src/ — service provider (what gets registered), Console/Commands (the generators you'll actually use), and any base controller/request/response classes.
   • composer.json — the illuminate/* version constraints tell you which Laravel versions are actually supported.
5. First use case: scaffold a single trivial resource (e.g., Product) end-to-end and run it. This exercises the generator, the base controller, the route registration, and the response shape in one go. Once you see the generated files, you know what the package is really giving you versus what you'd write by hand.

Implementation Patterns

Scaffold-per-resource workflow. The core value proposition is "fast REST API." The typical loop is: run the generator for a new model → inspect the generated controller/request/resource/routes → adjust the model/migration → commit. Treat generated code as a starting point, not a black box — read every generated file once so you know what to override later.

Inherit from the base classes, don't fork them. Most packages in this space ship a base controller (and often a base request or response helper). Extend those in your app-scoped controllers so you get the standard JSON envelope, pagination handling, and validation error formatting for free, and pick up fixes via Composer updates.

Standardize your API contract early. Decide whether you're using the package's default response envelope or your own. If your frontend/consumers expect a specific shape ({ data, meta }, JSON:API, etc.), override the base controller's response methods once in an App\Http\Controllers\ApiController that extends the package base — every generated controller then inherits the correct shape.

Pair with Laravel Sanctum/Passport. The package handles CRUD plumbing, not auth. Protect generated routes with middleware (auth:sanctum) at the routes/api.php group level, or wrap the generated route registration in a middleware group in your service provider.

Index filtering/pagination. If the package exposes query-param filtering (common in this class of library), define a whitelist of filterable fields per resource to avoid leaking arbitrary column access. Test ?page=, ?per_page=, and ?sort= behavior against your DB engine before relying on it.

Testing generated endpoints. Add a Pest/PHPUnit feature test per generated resource immediately after scaffolding. Generated code drifts from your model's actual validation rules fast; a feature test that hits every endpoint catches it.

Route caching. Verify php artisan route:cache still works after adding generated routes — closures or non-serializable bindings in generated route files are the usual failure mode.

Gotchas and Tips

• Small package, low maintenance signal. 11 stars and a last release in May 2024 means: audit src/ before production use, check open issues, and be prepared to vendor/fork if you hit a blocking bug. Prefer using it for internal/prototype APIs rather than long-lived public surfaces you can't patch.
• Laravel version compatibility. Check composer.json for the illuminate/* constraint. If it caps below your Laravel version, Composer will refuse to install — don't force it with --ignore-platform-reqs; the base classes likely depend on internals that changed.
• Regeneration overwrites custom code. Generators in this category often write controller/request files unconditionally. Before re-running a generator, check whether it skips existing files (look for --force/--overwrite flags). Keep generated code in git so you can diff and revert.
• Namespaces and paths are configured, not hardcoded. If generated files land in the wrong place, the fix is almost always in the published config (model namespace, controller namespace, route file) — not in the package source.
• Response format is opinionated. If your consumers reject the default envelope, override at the base-controller level (App\Http\Controllers\ApiController) rather than editing each generated controller. That's the intended extension point and keeps updates mergeable.
• Debugging generation. Use php artisan list | grep -i pentacraft to enumerate commands, php artisan route:list to confirm routes registered, and php artisan tinker to inspect any container bindings the service provider registers. If the provider isn't auto-discovered (older Laravel or a mis-declared extra.laravel block), register it manually in config/app.php.
• Documentation language. README and inline docs are Portuguese. If your team isn't Portuguese-speaking, write a short internal cheat-sheet of the commands and config keys you actually use — future you will thank you.
• Extension points to prefer: published config, base-class inheritance, and container bindings in your own AppServiceProvider. Avoid editing files under vendor/ — Composer will overwrite them on the next composer update.