Writing your own transformers | laravel-url-ai-transformer | Spatie SPATIE Laravel URL AI Transformer ============================= spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-url-ai-transformer](https://spatie.be/docs/laravel-url-ai-transformer/v2) Basic-usage Writing your own transformers Version v2 v1 Other versions for crawler [v2](https://spatie.be/docs/laravel-url-ai-transformer/v2) [v1](https://spatie.be/docs/laravel-url-ai-transformer/v1) Writing your own transformers - [ Introduction ](https://spatie.be/docs/laravel-url-ai-transformer/v2/introduction) - [ Support us ](https://spatie.be/docs/laravel-url-ai-transformer/v2/support-us) - [ Installation & setup ](https://spatie.be/docs/laravel-url-ai-transformer/v2/installation-setup) - [ Questions and issues ](https://spatie.be/docs/laravel-url-ai-transformer/v2/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-url-ai-transformer/v2/changelog) - [ About us ](https://spatie.be/docs/laravel-url-ai-transformer/v2/about-us) Basic usage ----------- - [ Getting started ](https://spatie.be/docs/laravel-url-ai-transformer/v2/basic-usage/getting-started) - [ Registering transformations ](https://spatie.be/docs/laravel-url-ai-transformer/v2/basic-usage/registering-transformations) - [ Writing your own transformers ](https://spatie.be/docs/laravel-url-ai-transformer/v2/basic-usage/writing-your-own-transformers) Advanced usage -------------- - [ Structured output ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/structured-output) - [ Customizing AI models ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/customizing-ai-models) - [ Customizing the stored result ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/customizing-the-result) - [ Conditional transformations ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/conditional-transformations) - [ Crawling URLs ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/crawling-urls) - [ Exploring command options ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/exploring-command-options) - [ Regenerating results ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/regenerating-results) - [ Handling failures ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/handling-failures) - [ Listening for events ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/events) - [ Using your own model ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/using-your-own-model) - [ Customizing the job ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/customizing-the-job) - [ Overriding actions ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/overriding-actions) - [ Testing transformers ](https://spatie.be/docs/laravel-url-ai-transformer/v2/advanced-usage/testing-transformers) Writing your own transformers ============================= ### On this page 1. [ Creating a basic transformer ](#content-creating-a-basic-transformer) 2. [ Customizing the content that is sent to the AI ](#content-customizing-the-content-that-is-sent-to-the-ai) 3. [ Returning structured output ](#content-returning-structured-output) 4. [ Customizing the stored result ](#content-customizing-the-stored-result) 5. [ Custom transformer types ](#content-custom-transformer-types) The real power of this package comes from writing your own transformers. Let's explore how to create custom transformers that fit your specific needs. Creating a basic transformer -------------------------------------------------------------------------------------------------------------------------------------------- You can generate a transformer with the `make:transformer` command: ``` php artisan make:transformer SummaryTransformer ``` This creates a transformer class in `app/Transformers`. Every transformer is a [Laravel AI](https://github.com/laravel/ai) agent. Extend the `Transformer` base class and implement `instructions()`, which returns the AI instructions to follow. The fetched URL content is sent along automatically as the prompt. ``` // app/Transformers/SummaryTransformer.php namespace App\Transformers; use Spatie\LaravelUrlAiTransformer\Transformers\Transformer; use Stringable; class SummaryTransformer extends Transformer { public function instructions(): Stringable|string { return 'Summarize this webpage content in 3 concise bullet points.'; } } ``` The base `Transformer` runs the AI call for you and stores the response on the transformation result. Customizing the content that is sent to the AI -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- By default, the fetched URL content is cleaned up before it is sent to the AI: scripts and styles are removed, HTML tags are stripped, whitespace is collapsed, and the result is limited to 6000 characters. This work is done by the `PrepareUrlContentAction`, which you can [replace with your own action](../advanced-usage/overriding-actions) to change the behavior for all transformers. To tweak the content for a single transformer, override the `content()` method: ``` class SummaryTransformer extends Transformer { public function instructions(): Stringable|string { return 'Summarize this webpage content in 3 concise bullet points.'; } public function content(): string { return (string) str(strip_tags($this->urlContent))->limit(1000); } } ``` You can now use your transformer: ``` Transform::urls('https://example.com/article') ->usingTransformers(new SummaryTransformer); ``` When a transformer runs, it has access to three properties: - `$this->url`: the URL being transformed - `$this->urlContent`: the fetched content from the URL - `$this->transformationResult`: the database model where you store results Returning structured output ----------------------------------------------------------------------------------------------------------------------------------------- Instead of free-form text, a transformer can return validated, machine-readable data by defining a schema. See [Structured output](../advanced-usage/structured-output) for the details. Customizing the stored result ----------------------------------------------------------------------------------------------------------------------------------------------- By default the transformer stores the AI's text response. You can post-process it, or save extra data on the model, by overriding `resultFrom()`. See [Customizing the stored result](../advanced-usage/customizing-the-result) for the details. Custom transformer types -------------------------------------------------------------------------------------------------------------------------------- By default, the transformer type is derived from the class name. You can override this: ``` class MyCustomTransformer extends Transformer { public function type(): string { return 'customType'; } // Other methods... } ``` You can use your custom type when retrieving a transformation result: ``` $ldJsonData = TransformationResult::forUrl('https://spatie.be/blog', 'customType'); ``` A good match? ------------- ### What we do best - All things Laravel - Custom frontend components - Building APIs - AI-powered features - Simplifying things - Clean solutions - Integrating services ### Not our cup of tea - WordPress themes - Cutting corners - Free mockups to win a job - "Just execute the briefing" In short: we'd like to be a **substantial part** of your project. [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)