Papercut Bridge Bundle Laravel Package

Getting Started

maillotf/papercut-bridge-bundle is a Symfony bundle, not a Laravel package, so there is no package auto-discovery, no publishable config, and no facade. Treat it as a thin wrapper around a Papercut XML-RPC client that you wire into Laravel yourself.

1. Install the dependency:

   composer require maillotf/papercut-bridge-bundle
   

2. Look first at MaillotF\Papercut\PapercutBridgeBundle\Service\PapercutService. It exposes the underlying client through public properties (e.g. $ps->user, $ps->printJob, etc.); that object graph is the real API surface you will use.
3. Translate the YAML config into Laravel config. Create config/papercut.php:

   return [
       'authentication' => [
           'protocol' => env('PAPERCUT_PROTOCOL', 'http'),
           'host'     => env('PAPERCUT_HOST', '127.0.0.1'),
           'port'     => env('PAPERCUT_PORT', '80'),
           'path'     => env('PAPERCUT_PATH', '/rpc/api/xmlrpc'),
           'token'    => env('PAPERCUT_TOKEN'),
       ],
   ];
   

4. Bind the service in AppServiceProvider::register():

   $this->app->singleton(PapercutService::class, function ($app) {
       return new PapercutService($app['config']->get('papercut'));
   });
   

5. First use case — resolve a user and read an attribute:

   public function show(PapercutService $ps, string $id)
   {
       return response()->json($ps->user->getUser($id)->getEmail());
   }
   

6. Verify connectivity with php artisan tinker before building anything on top; a bad token or path fails at call time, not construction time.

Implementation Patterns

• Service provider + config is the whole integration. Do the YAML→PHP translation once, key everything off env vars, and never let the token live in committed config.
• Inject PapercutService, not the underlying client. In controllers, queued jobs, console commands, and scheduled tasks, type-hint the service and let the container resolve it. Prefer constructor injection in jobs/commands so serialization stays clean.
• Wrap it behind your own interface. Define App\Contracts\PapercutClient and have PapercutService satisfy it (or an adapter implement it). This gives you a seam to swap in a fake during tests and insulates the app from the bundle's public-property API.
• Use it inside queued jobs for anything slow. XML-RPC calls are network round-trips; batch user lookups, balance checks, or print-job reads in a job with retries and backoff rather than in the request cycle.
• Ad-hoc facade (optional). If your team prefers facades, register one in the provider pointing at the singleton; otherwise plain injection is clearer and easier to mock.
• Configuration fallback shape. The bundle accepts either the protocol/host/port/path combination or a single full path URL. Standardize on one in config/papercut.php and document it so nobody mixes the two styles.
• Health check pattern. Add a small artisan command that performs a harmless lookup (e.g. $ps->user->getUser($knownId)) and reports pass/fail — useful in deploy pipelines and on-call runbooks.
• Testing. In TestCase, swap the contract binding for a fake returning stub user objects, so feature tests never touch a live Papercut server.

Gotchas and Tips

• It is not a Laravel package. Expect none of the usual php artisan vendor:publish, config/*.php auto-merge, or alias registration. If the service constructor signature doesn't match the array you pass, you'll get a TypeError at resolution time — read the bundle's Service/PapercutService.php before wiring.
• Don't paste YAML into framework.yaml. Laravel has no framework.yaml and no Symfony service container in this sense. The services.yaml snippet in the docs is Symfony-only.
• Two config styles, one wins. Mixing path (full URL) with protocol/host/port can silently produce a malformed endpoint. protocol/port are strings in the docs — keep them as strings in your config array to match the expected shape.
• Token handling. Keep PAPERCUT_TOKEN in .env/secret manager, add it to .env.example empty, and never log request payloads containing it. Verify with php artisan config:clear after changing env vars — cached config is the most common "it worked in tinker but not in the app" cause.
• No built-in retry or timeout knobs. Wrap calls in your own try/catch, set sensible timeouts, and decide whether failures are fatal or degrade gracefully. Surface the raw XML-RPC fault message in logs; it usually names the exact auth or method problem.
• Responses are getter objects. Results come back as value objects (getEmail(), etc.), not arrays. Don't toArray() them expecting array access; check the underlying client class for available getters.
• Public property access ($ps->user). This is convenient but brittle — an upstream rename breaks call sites silently. Funnel access through your adapter so upgrades touch one file.
• Extension points are limited. The intended customization is decorating/replacing papercut.service in the container. Use Laravel's container binding — bind the concrete to an interface, then extend via decorator if you need logging, metrics, or caching around calls.
• Debugging checklist: correct path including /rpc/api/xmlrpc, reachable host/port from the container, valid token, user ID sent as a string, and the Papercut server's XML-RPC endpoint enabled. Log one raw request/response pair when first integrating.