Resource Laravel Package

Getting Started

1. Install it the standard Composer way.

   composer require bfg/resource
   

   The package is small enough that auto-discovery (if a service provider ships) or a manual providers entry in config/app.php is the only wiring you'll need. Check composer.json in the repo for the extra.laravel.providers key before assuming you're done.

2. Read the source before the README. With 1 star and 0 dependents, documentation will lag the code. Start with:

   • src/ — see what actually ships (base class, traits, collection helpers).
   • composer.json — confirm the PSR-4 namespace (likely Bfg\Resource\...) and minimum Laravel version.
   • README.md — expect a skeleton; treat any examples as aspirational until you've run them.

3. First real use case. Given the description ("a small addition to the resources"), the entry point is almost certainly a base resource class you extend instead of Illuminate\Http\Resources\Json\JsonResource. Create one resource against a model you already expose, e.g.:

   use Bfg\Resource\...; // confirm the actual class name in src/
   
   class UserResource extends /* package base */ 
   {
       public function toArray($request): array
       {
           return [
               'id'    => $this->id,
               'name'  => $this->name,
               'email' => $this->email,
           ];
       }
   }
   

   Then return it from a controller and hit the route with Accept: application/json. If the payload shape is what you expect, the package is behaving as a thin wrapper; if not, you've found your first integration quirk.

4. Write a smoke test immediately. One feature test that hits the endpoint and asserts the JSON structure will save you hours, because the package's behavior is under-documented.

Implementation Patterns

• Extend, don't wrap. The most likely design is a base Resource class extending Laravel's JsonResource. Extend it and keep your toArray() logic in your own class — treat the package as a thin convention layer, not a framework.
• Use it as the single serialization boundary. Return resources from controllers and route definitions (Route::get(...)->...), never from models or repositories. This keeps the package's behavior isolated to the HTTP edge, so you can rip it out later if needed.
• Collections: if the package ships a collection class (analogous to ResourceCollection), use it for list endpoints so pagination metadata (links, meta) is handled consistently. Verify the shape it emits against Laravel's default before your frontend depends on it.
• Conditional relationships: keep using whenLoaded() / when() from Laravel — these are inherited if the base class extends JsonResource. The package addition, whatever it is, rarely replaces these.
• Controller integration:

  public function show(User $user)
  {
      return new UserResource($user);
  }
  

  Keep the response class as the only thing the controller knows about; don't sprinkle package-specific helpers across controllers.
• Incremental adoption. Start with one resource on a low-traffic endpoint. If the package only adds sugar (helpers, defaults), rolling it out further is cheap; if it changes serialization semantics, you want to find that out on one endpoint, not fifty.

Gotchas and Tips

• Tiny package, negligible maintenance signal. 1 star, 0 dependents, and a vague one-line description mean:
  • No public bug reports to learn from.
  • No community answers when something goes wrong.
  • API may break between patch releases without a changelog. Pin the version in composer.json ("bfg/resource": "x.y.*") so an unexpected update doesn't silently change your API responses.
• Namespace collision risk. If the base class or helper names (e.g., Resource) overlap with App\Http\Resources\... or Illuminate\Http\Resources\..., imports get confusing fast. Alias explicitly:

  use Bfg\Resource\Resource as BfgResource;
  

• Verify Laravel compatibility. A low-traffic package often declares a laravel/framework constraint that lags current versions. Check composer.json and run composer why-not bfg/resource if installation fails on your Laravel version.
• Debug serialization issues by dumping the resolved instance. If the JSON output is unexpected, dd($resource->resolve(request())) reveals exactly what the package's toArray produced versus what Laravel wrapped around it.
• Watch for overridden lifecycle hooks toArray(), resolve(), with(), additional(). These are the most likely extension points in a lightweight resource package. If behavior surprises you, grep the package source for these method names — that's where the "small addition" lives.
• Check for a config file. Some resources packages add a config/resource.php with defaults (wrapper key, pagination meta shape). If it exists, publish it (php artisan vendor:publish --tag=...) so you control the defaults rather than the package author.
• Have an exit plan. Because the dependency surface is thin, keep your resources' toArray() free of package-specific method calls where possible. If the package stalls, swapping back to JsonResource should be a search-and-replace of the base class, not a rewrite.