PHPackages basillangevin/instructor-laravel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. basillangevin/instructor-laravel ActiveLibrary[Utility & Helpers](/categories/utility) basillangevin/instructor-laravel ================================ Structured outputs for LLMs using Spatie Data objects. v0.1.0(1y ago)20[5 PRs](https://github.com/BasilLangevin/instructor-laravel/pulls)MITPHPPHP ^8.3CI passing Since Feb 11Pushed 3mo ago1 watchersCompare [ Source](https://github.com/BasilLangevin/instructor-laravel)[ Packagist](https://packagist.org/packages/basillangevin/instructor-laravel)[ Docs](https://github.com/basillangevin/instructor-laravel)[ GitHub Sponsors](https://github.com/BasilLangevin)[ RSS](/packages/basillangevin-instructor-laravel/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (16)Versions (9)Used By (0) Structured outputs for LLMs using Spatie Data objects. ====================================================== [](#structured-outputs-for-llms-using-spatie-data-objects) [![Latest Version on Packagist](https://camo.githubusercontent.com/093e66e026e5be5635a367fc3337a41b33a79a2776248bac82d328dd3807a655/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626173696c6c616e676576696e2f696e7374727563746f722d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/basillangevin/instructor-laravel)[![GitHub Tests Action Status](https://camo.githubusercontent.com/f7f269a684b9cf39229307cb1f8cc6da72c7690f1cccd17729d1b38389697c4b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f626173696c6c616e676576696e2f696e7374727563746f722d6c61726176656c2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/basillangevin/instructor-laravel/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/94e6294acb9d71c21d950fad199d7795c9eae058c61bb91ce12b9a84a64eab04/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f626173696c6c616e676576696e2f696e7374727563746f722d6c61726176656c2f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/basillangevin/instructor-laravel/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/bfd9d40bf59272697f2845e7571416695defacb4097f270c05478d3c25fa9950/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f626173696c6c616e676576696e2f696e7374727563746f722d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/basillangevin/instructor-laravel) Instructor Laravel turns LLM (Large Language Model) responses into [spatie/laravel-data](https://spatie.be/docs/laravel-data/v4/introduction) objects, helping you easily integrate LLMs into your applications. Installation ------------ [](#installation) You can install the package via composer: ``` composer require basillangevin/instructor-laravel ``` You can publish the config file with: ``` php artisan vendor:publish --tag="instructor-laravel-config" ``` These are the contents of the published config file: ``` use EchoLabs\Prism\Enums\Provider; // config for BasilLangevin/InstructorLaravel return [ /* |-------------------------------------------------------------------------- | Default LLM Provider |-------------------------------------------------------------------------- | | This value is the default LLM provider that this package will use to | generate a structured response that it will transform into a Data | object. You may also set LLM providers on a per-request basis. */ 'provider' => Provider::OpenAI, /* |-------------------------------------------------------------------------- | Default LLM Model |-------------------------------------------------------------------------- | | This value is the default LLM model that this package will use | for the LLM provider when generating a structured response. | You may also set the model each time you make a request. */ 'model' => 'gpt-4o', ]; ``` Introduction ------------ [](#introduction) Instructor Laravel is built on top of [echolabsdev/prism](https://prism.echolabs.dev/): a fantastic package that provides a unified interface to work with various LLM providers. Instructor Laravel extends the [Structured Outputs](https://prism.echolabs.dev/core-concepts/structured-output.html) feature of Prism, allowing you to use [spatie/laravel-data](https://spatie.be/docs/laravel-data/v4/introduction) objects as your data schema. The package modifies two methods from Prism: `withSchema` and `generate`. All other Prism methods are available and work as expected. Basic Usage ----------- [](#basic-usage) Because this package transforms LLM responses into `spatie/laravel-data` objects, we'll start by defining a `Data` object. ``` use Spatie\LaravelData\Attributes\Min; use Spatie\LaravelData\Data; class BirdData extends Data { public function __construct( public string $species, /** The average wingspan of the bird in centimeters. */ public int $wingspan, #[In(['forest', 'prarie', 'wetland'])] public string $habitat, ) {} } ``` Then, we'll build our LLM request by: - starting with the `Instructor` facade, - passing our `Data` object class to the `withSchema` method, - using standard Prism [structured output methods](https://prism.echolabs.dev/core-concepts/structured-output.html) to configure the request, then - calling the `generate` method. ``` use BasilLangevin\InstructorLaravel\Facades\Instructor; use EchoLabs\Prism\Enums\Provider; $bird = Instructor::make() ->withSchema(BirdData::class) ->using(Provider::OpenAI, 'gpt-4o') ->withPrompt('Tell me about a bird found on the West Coast of Canada.') ->generate(); ``` The `generate` method will return a `BirdData` object from the LLM response. ``` BirdData { +species: "Western Bluebird" +wingspan: 34 +habitat: "forest" } ``` ### Collections of Data objects [](#collections-of-data-objects) Instructor Laravel also supports transforming responses that contain collections of `Data` objects. ``` $birds = Instructor::make() ->withCollectionSchema(BirdData::class) ... ``` The `generate` method will return a `Collection`` of `BirdData` objects. You may pass a custom `Collection` class name as the second argument of `withCollectionSchema` to use a custom collection class: ``` $birds = Instructor::make() ->withCollectionSchema(BirdData::class, BirdCollection::class) ... ``` Validation and retries ---------------------- [](#validation-and-retries) Instructor Laravel will automatically validate the LLM response against the `Data` object's rules. If the LLM response doesn't match the expected structure, Instructor Laravel will call the LLM again with any errors it encountered, helping the LLM generate a response that matches the expected structure. By default, the request will be retried up to 3 times. You can change this by calling `withRetries(...)` or `withoutRetries()`: ``` $bird = Instructor::withSchema(BirdData::class) ->withRetries(5) ... ``` The `withRetries` method accepts the same arguments as Laravel's `retry` helper (excluding the `$callback` argument). The number of retries will be added to the initial request, so if you pass `3` to `withRetries`, the request will be made up to 4 times in total (1 initial attempt + 3 retries). Improving LLM response reliability ---------------------------------- [](#improving-llm-response-reliability) To improve the LLM's understanding of the expected response, Laravel Instructor transforms the `Data` class into a JSON Schema and passes it to the LLM. Under the hood, schemas are generated using [basillangevin/laravel-json-data-schema](https://github.com/basillangevin/laravel-json-data-schema). This package adds additional information to the generated schema by transforming: - PHPDoc block [summaries and descriptions](https://github.com/BasilLangevin/laravel-data-json-schemas?tab=readme-ov-file#schema-annotations), - most `spatie/laravel-data` [validation attributes](https://github.com/BasilLangevin/laravel-data-json-schemas?tab=readme-ov-file#validation-rules), and - `Title`, `Description`, and `CustomAnnotation` [attributes](https://github.com/BasilLangevin/laravel-data-json-schemas?tab=readme-ov-file#schema-annotations). All of this information is available to the LLM from the very first request, so it can be helpful to annotate your `Data` classes more information as needed. Testing ------- [](#testing) Each PHP file in this package has a co-located Pest test file named `{FileName}Test.php`. This package achieves 100% test coverage, 100% mutation coverage, and 100% PHPStan coverage coverage at level 10. The following commands can be used to test the package: ``` # Run the standard test suite ./vendor/bin/pest --parallel # Run the test suite and generate a coverage report ./vendor/bin/pest --coverage --parallel # Run mutation tests ./vendor/bin/pest --mutate --parallel --covered-only # Run PHPStan at level 10 ./vendor/bin/phpstan analyse ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [BasilLangevin](https://github.com/BasilLangevin) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 33 — LowBetter than 72% of packages Maintenance63 Regular maintenance activity Popularity3 Limited adoption so far Community10 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 86.4% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 507d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/109987292?v=4)[Basil Langevin](/maintainers/BasilLangevin)[@BasilLangevin](https://github.com/BasilLangevin) --- Top Contributors [![BasilLangevin](https://avatars.githubusercontent.com/u/109987292?v=4)](https://github.com/BasilLangevin "BasilLangevin (38 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (3 commits)") --- Tags laravelBasilLangevininstructor-laravel ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/basillangevin-instructor-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/basillangevin-instructor-laravel/health.svg)](https://phpackages.com/packages/basillangevin-instructor-laravel) ``` ### Alternatives [spatie/laravel-pdf Create PDFs in Laravel apps 1.0k4.8M47](/packages/spatie-laravel-pdf)[codewithdennis/filament-select-tree The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths. 329530.5k29](/packages/codewithdennis-filament-select-tree)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3914.6k](/packages/rawilk-profile-filament-plugin)[worksome/exchange Check Exchange Rates for any currency in Laravel. 124603.0k](/packages/worksome-exchange)[tarfin-labs/event-machine Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail. 199.4k](/packages/tarfin-labs-event-machine) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)