Clients Bundle Laravel Package

Getting Started

tefps/clients-bundle is a Symfony bundle, so Laravel will never auto-discover it. Composer installs the code, but nothing registers itself. Your first task is reconnaissance, then manual wiring.

1. Install and inspect before writing a line of code.

   composer require tefps/clients-bundle
   composer show -a tefps/clients-bundle     # version, deps, PHP constraint, autoload namespace
   

   Read, in this order:

   • README.md — config keys and a usage example (if any).
   • DependencyInjection/Configuration.php — the authoritative config tree, types, defaults. This is what config/clients.php should mirror.
   • Resources/config/services.xml (or .yaml) — service IDs, class names, constructor arguments. This is the list of things you must build by hand.
   • DependencyInjection/*Extension.php — shows how config parameters map onto those constructor arguments.
   • grep -r "^namespace" vendor/tefps/clients-bundle/src | head — confirm the actual root namespace. The package name and repo name differ, so don't trust the GitHub URL.

2. Create config/clients.php mirroring the Symfony tree exactly. Any key the YAML/XML services file references must exist here, or your hand-wired container will blow up with missing-argument errors at boot:

   // config/clients.php
   return [
       'storage'   => env('CLIENTS_STORAGE', 'doctrine'),
       'entity'    => [
           'class' => \Tefps\ClientsBundle\Entity\Client::class,
       ],
       'metadata'  => [
           'contact_fields' => ['email', 'phone'],
       ],
   ];
   

3. Register a service provider. You are hand-reproducing services.xml. Bind the service-layer classes as singletons and, if the bundle expects an EntityManager, bind a Doctrine EntityManagerInterface or point it at your own Eloquent model. If it only ships a "ClientService" with constructor args, wire those literally:

   // app/Providers/ClientsServiceProvider.php
   public function register(): void
   {
       $this->app->singleton(\Tefps\ClientsBundle\Service\ClientService::class, function ($app) {
           return new \Tefps\ClientsBundle\Service\ClientService(
               config('clients.storage'),
               // whatever the services.xml says goes here — read it, don't guess
           );
       });
   }
   

4. First use case — create a client record. That's the primary, documented scenario. Drive it through your own service class, not the vendor one:

   $client = app(ClientGateway::class)->create([
       'name'  => $request->input('name'),
       'email' => $request->input('email'),
       'phone' => $request->input('phone'),
   ]);
   

If after step 1 you find the bundle is essentially a thin wrapper around one entity and one service, stop and ask whether a 100-line Eloquent model with a domain-shaped service does the same job with zero vendor risk. For a bundle at 0 stars and 0 dependents, this is not a rhetorical question.

Implementation Patterns

• Wrap, always. No Tefps\ClientsBundle\* type should appear in a controller, form request, job, or Blade view. Define a ClientGateway interface in app/Contracts with methods shaped around your domain (register, updateContact, findByEmail), and put the vendor call behind it. The reason isn't purity — it's that when the vendor is abandoned, the interface is your migration seam and the adapter is the only file to rewrite.

• Adapters as the injection point. Bind the interface to a TefpsClientGateway in a dedicated service provider. Feature-flag the binding so you can swap to an EloquentClientGateway implementation without touching consumers if the package fails review or gets dropped later:

  $this->app->bind(ClientGateway::class, match (config('clients.driver')) {
      'tefps'    => TefpsClientGateway::class,
      default    => EloquentClientGateway::class,
  });
  

• Map at the boundary. If the bundle ships a Client entity (Doctrine or plain PHP), don't persist it as-is alongside your Eloquent models and don't return it from controllers. Convert to a DTO on the way out. This keeps serialization, validation, and API contracts under your control rather than whatever the bundle's entity happens to expose.

• Background work is the natural home. Client create/update calls that hit external storage or need retries belong in a queued job (ProcessClientCreation). The service layer is generally synchronous; wrap it in a job with retryUntil, backoff, and failed() logging.

• Config via config() helper, not the container's %parameters%. Symfony bundles expect parameters injected at container compile time. In Laravel, resolve config at runtime inside the adapter's constructor and cache it on the instance. Don't try to reconstruct Symfony's parameter bag.

• Testing. Contract tests, not integration tests, against the vendor classes. Mock ClientGateway in feature tests. For the adapter itself, write one integration test that exercises the real service layer against an in-memory database (SQLite) so you catch wiring mistakes at CI time, not at deploy time.

• Console/seeders. If the bundle's entity is Doctrine-backed, Laravel's factories and seeders won't work with it. Seed through the gateway instead, or skip seeding entirely and treat the bundle as read-only during rollout.

Gotchas and Tips

• No auto-discovery, no vendor:publish, no service provider. Symfony bundles bootstrap via Kernel::registerBundles(). Laravel has no equivalent. Everything after composer require is your code. Budget a half-day for wiring even a small bundle.

• Doctrine entities ≠ Eloquent models. If the bundle ships a Client entity, it almost certainly implements Doctrine EntityManager conventions (getId(), annotations or PHP attributes, no $fillable, no casts). Eloquent will not hydrate it. Either keep the vendor entity completely out of your persistence layer and store client data in your own Eloquent model, or stand up Doctrine alongside Eloquent — which is a much bigger lift than it sounds. The pragmatic answer for a Laravel shop is usually: use the vendor's service logic as reference, own the persistence yourself.

• The config tree is strict. Symfony's Configuration.php defines typed nodes with defaults and required args. If you mirror it loosely in config/clients.php and the bundle's Extension code does $config['credentials']['id'], you'll get null pointer exceptions at runtime. Grep the extension and services file for every %clients.*% placeholder and make sure each one resolves.

• Composer version pins are the real long-term risk. A 0-star Symfony bundle pins symfony/* components at whatever version the author had installed. Laravel ships its own transitive symfony/* set. composer update may be quiet today and block a Laravel major upgrade in six months. Pin by exact version (or commit hash if no tags exist), commit the lockfile, and put "revisit on next Laravel major" on the calendar.

• Assume no maintenance. 0 stars, 0 dependents, no visible issue activity. There is no CVE process, no changelog, no bus factor beyond the publisher. If this ends up in production, fork the repo internally, mirror it in your own VCS, and treat upstream as a reference implementation. Apply patches yourself.

• Debugging the wiring. If something fails silently at boot, run php artisan tinker and try to instantiate the vendor service directly. Errors from miswired constructor arguments show up there as ArgumentCountError or TypeError before they ever hit a controller. Log::debug(print_r($container->get(...) )) is coarse but effective for a first pass.

• Extension points are Symfony-shaped. The bundle may offer tagged services, compiler passes, or event subscribers. None of those hooks exist in Laravel. Extend by composition (wrap the service) or by class inheritance at your adapter layer — not by trying to reuse the bundle's extension mechanism.

• Licence and provenance check first. Before writing a single adapter line, confirm the licence permits forking and self-maintenance. A bundle with zero adoption and no stated licence should not enter a compliance-sensitive codebase without legal sign-off, regardless of how convenient the wiring is.

• Watch the naming mismatch. The package (clients-bundle) and repository (tefps-clients-php) don't match, and the description suggests generic client records while the repo name suggests a specific upstream service. Confirm before you budget: what does this bundle actually do — manage your own client data, or call an external API? The wiring story above assumes the former. If it's the latter, expect an HTTP client underneath and adjust your retry/idempotency and credential-management patterns accordingly.