Music Gpt Bundle Laravel Package

Getting Started

Read this first: it is not a Laravel package. Despite the "bundle" name in the title, yoanbernabeu/music-gpt-bundle is a Symfony bundle (Symfony\Component\HttpKernel\Bundle\Bundle), documented for Symfony ^7.0 || ^8.0. There is no Laravel service provider, no package auto-discovery, and no facade. Your first 10 minutes should be spent answering "can I even install this?" before writing any feature code.

Checklist before composer require:

• PHP >= 8.4. Hard floor in composer.json. Laravel 11/12 projects commonly run 8.2/8.3 — on those, install fails at the platform check. Verify with php -v and your config.platform.php in composer.json.
• Symfony HTTP kernel. Laravel ships some Symfony components (http-foundation, console, process, finder, error-handler) but not symfony/http-kernel. The bundle class extends it, so Composer will pull it in — and your autoloader will never register the bundle.
• Container mismatch. The headline "simple dependency injection with Symfony autowiring" does not exist in Laravel. Illuminate\Container will not resolve the bundle's services for you.

Where to look in the source, in this order:

1. src/ for the client/service interfaces — these are what you bind or wrap.
2. src/Dto/ and src/Enum/ — the request/response shapes. The release promises full PHP 8.4 typing here, so these are the most portable part of the package and the most likely thing you'll actually reuse.
3. The bundle's DependencyInjection/Configuration.php (or config/) to learn the real config keys — the release notes don't name them.
4. The README examples for each endpoint.

First use case: do not start with music generation. Start with Voice Management (search/browse voice models). It is read-only, cheap, and verifies auth, HTTP wiring, config, and DTO hydration in one shot. Only after that works should you touch TTS or music generation, which consume credits and are asynchronous.

Minimal Symfony usage (for reference, even if you're porting it):

# config/packages/music_gpt.yaml
music_gpt:
    api_key: '%env(MUSIC_GPT_API_KEY)%'

Laravel equivalent — you build this yourself:

// app/Providers/MusicGptServiceProvider.php
public function register(): void
{
    $this->app->singleton(MusicGptClient::class, fn () => new MusicGptClient(
        apiKey: config('services.music_gpt.key'),
    ));
}

// config/services.php
'music_gpt' => ['key' => env('MUSIC_GPT_API_KEY')],

Implementation Patterns

Wrap the package behind your own gateway interface. This is the single highest-leverage pattern for a 0.1.0 dependency. Define App\Contracts\MusicGenerator, implement it with the bundle's client, and bind it in a provider. Every controller, job, and test talks to your interface. When the API surface shifts (and at 0.x it will), or when you migrate off Symfony, you change one class.

Treat every conversion as an async job. Generation, voice covers, TTS, and stem extraction are all "submit → get a conversion ID → poll" per the Conversion Tracking feature. The shape that works:

final class GenerateMusicJob implements ShouldQueue
{
    public int $timeout = 600;
    public int $tries = 3;
    public array $backoff = [10, 60, 300];

    public function __construct(public readonly MusicRequestData $request) {}

    public function handle(MusicGenerator $generator): void
    {
        $conversion = $generator->submit($this->request);   // returns your DTO
        $generator->awaitCompletion($conversion->id);       // polls with backoff
        $generator->downloadTo($conversion->id, "music/{$conversion->id}.mp3");
    }
}

Never poll inside a web request. Never poll in a tight loop — audio jobs run tens of seconds to minutes, and a naive while loop will burn worker CPU and hit rate limits.

Persist the conversion ID in your own table. Add music_conversions with (id, external_id, status, type, user_id, result_path, error, created_at). The package's Conversion Tracking is stateless; your audit trail, retry logic, and "show me my generated tracks" UI all live in your schema, not the bundle's DTOs.

Stream files, don't buffer them. Audio payloads are large. Upload via Storage::disk()->putFileAs() with a stream, and download to a temp path then move — not file_get_contents into a string. On Laravel, Http::withBody($stream) style streaming beats materialising the whole file.

Keep DTOs at the boundary. Map the package's DTOs/Enums into your own models in the gateway. Do not let YoanBernabeu\MusicGpt\Dto\* types leak into Blade views, controllers, or Eloquent casts. This is also what makes the package swappable if a Laravel-native SDK appears.

Fake it in tests. Because you bound an interface, tests use a FakeMusicGenerator that returns canned DTOs. Do not let PHPUnit call the real API — the suite becomes slow, flaky, and expensive. Reserve one opt-in integration test behind an env flag (MUSIC_GPT_INTEGRATION=1).

Config discipline: API key from env() only, never committed, and referenced as config('services.music_gpt.key') at call sites so config:cache works.

Gotchas and Tips

• No Laravel integration exists, and none is promised. The release notes describe Symfony autowiring, Symfony config files, and a Symfony bundle class. In a Laravel app you are writing the adapter layer yourself. Budget for that; it is not a composer require and go.
• PHP 8.4 is a hard blocker, not a soft one. If your app is on 8.2/8.3, this package is simply unavailable until you upgrade. Do not try to bypass with --ignore-platform-reqs — the codebase advertises PHP 8.4-only syntax (property hooks, asymmetric visibility are plausible given "full PHP 8.4 type safety"), and you'll get parse errors at runtime.
• Symfony ^7.0 || ^8.0 may conflict with Laravel's pinned Symfony components. Laravel constrains specific component versions; a bundle requiring Symfony 8 can drag transitive components out of sync. Run composer why-not before assuming it resolves.
• 0.1.0 means the API is not stable. Composer treats 0.x minors as potentially breaking. Pin narrowly ("yoanbernabeu/music-gpt-bundle": "0.1.*"), read every changelog, and lean on the gateway wrapper.
• No cost or quota guardrails are mentioned. Music generation and TTS consume API credits per call. Add a per-user rate limit, a daily cap, and an idempotency key on submit so a retried job doesn't double-charge you.
• Failure modes are underspecified in the notes. "Comprehensive exception handling" tells you exceptions exist, not what they are. Enumerate the package's exception classes early and catch them at your gateway boundary — map to your own MusicGenerationFailed so the rest of the app isn't coupled to the vendor's hierarchy.
• Retries need care: not every failure is retryable. Auth/validation errors should fail fast ($this->fail()); network/5xx should back off. Blanket tries = 3 will happily retry a 401 three times and triple your log noise.
• Set explicit HTTP timeouts. Default client timeouts are too long for a queue worker and too short for a synchronous submit that generates audio. Separate connect timeout from total timeout.
• Polling has no webhook. The feature list shows status tracking only — assume you poll. Record last_polled_at and give up after a bounded window rather than polling an abandoned conversion forever.
• Extension points are interfaces + DI. If you are on Symfony, you can decorate the client services cleanly (logging decorator, metrics decorator). If you're on Laravel, replicate this with a decorator bound in your provider — same benefit.
• Debugging tip: log the conversion ID on submit and on every status check, correlated with your job's attempts(). Nearly every "it's stuck" report is a job that died and a conversion that kept running server-side; the ID is your only thread to pull.
• Verify audio constraints yourself. Accepted formats, max input size, and output format are not stated in the release notes. Test with a real file before building UI around an assumption — a 50 MB WAV rejected at the API is a bad way to find out.
• The quality signals are genuine but narrow. PHPStan max + PHPUnit + PHP-CS-Fixer means the typing is trustworthy; it says nothing about API-version drift, so pin and monitor.