Weave Code
Laravel Url Ai Transformer Laravel Package
spatie/laravel-url-ai-transformer
Spatie package for transforming URLs and web content with AI. Define Laravel AI agent transformers to extract structured data, generate summaries, or apply custom transformations; results are stored in the database and run via an Artisan command.
spatie/laravel-url-ai-transformer lets you transform URLs and their content using AI. Define a transformer as a Laravel AI agent, point it at one or more URLs, and let it extract structured data, generate summaries, or apply custom transformations. Results are stored in a database and can be retrieved at any time.
- Transformer agents: specify AI instructions and optional content to send.
- Structured output, such as ld+json data, summaries, or extracted fields.
- Artisan command: run configured transformations via
php artisan transform-urls. - Persistent results stored in the database and available later.
- Upgrade path from v1 documented in
UPGRADE.md.
Frequently asked questions about Laravel Url Ai Transformer
- How do I install spatie/laravel-url-ai-transformer in a Laravel app?
- Install it with Composer using composer require spatie/laravel-url-ai-transformer, then run the package migrations so the transformation results table exists. Because transformers are built on Laravel AI agents, you also need the Laravel AI package installed and an AI provider configured. After that you can define a transformation with Transform::urls(...)->usingTransformers(...) and run php artisan transform-urls. Expect a composer require, a migration, a transformer class, and a scheduled command to get the happy path working.
- Which Laravel versions does laravel-url-ai-transformer support?
- Version 2.0.0 of the package targets Laravel 12 and PHP 8.x, because it replaced Prism with the official Laravel AI package. Version 1.x was built on the Prism line and is not the version you should start new work on. If your application is still on an older Laravel release, the Laravel 12 upgrade should be planned as part of the same workstream rather than a separate one.
- How do I run URL transformations and can I schedule them?
- Configured transformations run through the transform-urls Artisan command, so php artisan transform-urls processes whatever URLs and transformers you have set up. Because it is a normal Artisan command, you can schedule it from your console kernel and use withoutOverlapping to avoid concurrent runs. The package does not add a queue system of its own, so pair it with your existing queue and scheduler setup. The README documents only the single-run flow, so verify batch and scheduling behavior against the source if you need more control.
- How do I retrieve the transformation results that were stored in the database?
- Results are persisted, so you do not need to call the AI model again at render time. You fetch them with the TransformationResult model, for example TransformationResult::forUrl($url, 'ldJson') to get the ld+json output for a specific URL. This is an enrich-on-write, read-from-the-database architecture, which keeps page renders off the model call path. Check the index and lookup cost of forUrl() if you expect hundreds of thousands of rows.
- How do I write a custom transformer instead of using LdJsonTransformer?
- A transformer is a Laravel AI agent, so you create your own agent class, define the instructions it must follow, and optionally specify which page content gets sent along. You then pass an instance to usingTransformers() in place of LdJsonTransformer, for example to generate summaries or apply custom instructions. The README only walks through the ld+json example, so anything beyond that means reading the source to understand the transformer contract. Give each transformer a distinct key so you can retrieve its results separately with forUrl().
- Can I transform multiple URLs at once, and is the transform-urls command idempotent?
- Transform::urls() is the fluent entry point for registering the URLs you want enriched, and the transform-urls command runs the configured transformers over them. Whether the command skips URLs that were already transformed or recomputes them on every run is not documented, so confirm that in the source before relying on it. Also check the timeout, retry, and partial-failure semantics, specifically whether one bad URL aborts the whole batch. If idempotency is not built in, guard it yourself by checking for an existing TransformationResult before processing.
- Should I start on v1 or v2, and how difficult is the upgrade?
- Start greenfield projects on v2.0.0 with Laravel AI. Do not begin new work on the 1.x line, since that dependency was already replaced by the maintainer and you would be adopting something with a known one-way migration ahead of it. If your team is already on 1.x, treat UPGRADE.md as a one-way migration and rehearse it on staging, budgeting for the Laravel 12 upgrade in the same effort. Pin an exact minor version and audit transitive dependencies, since Laravel AI and its provider SDKs are newer than the package itself.
- Does the package protect against SSRF when fetching arbitrary URLs?
- Server-side fetching of arbitrary URLs means real SSRF exposure, including internal IPs and cloud metadata endpoints, plus robots.txt questions and pages large enough to blow up token counts. The README does not state whether any guards exist for blocked hosts, redirect limits, or robots.txt behavior, so assume none by default. Put the package behind your own URL validation and allowlisting, and restrict outbound network access from the worker. Also decide whether it stores the fetched raw HTML, which affects whether you can re-run a transformer without re-fetching.
- Are the AI transformer outputs validated, and how do I handle prompt injection?
- Page content is attacker-controlled input, so prompt injection is a genuine risk and the generated output should be treated as untrusted. The package does not document schema validation of transformer results, so assume outputs may be free text or malformed JSON that you must parse and validate yourself. If generated ld+json is injected into a rendered page, bad or hostile model output becomes an XSS and SEO liability, so validate and sanitize before use. Prefer structured output or your own JSON schema checks where the underlying Laravel AI agent supports them.
- Can I cap AI token usage and cost per URL or per run?
- Cost per URL is effectively unbounded out of the box, since the README documents no token caps, truncation strategy, or per-run budget controls. Large pages can inflate prompts quickly, so truncate or extract the content you send to the agent before handing it over. Add your own rate limiting and spend monitoring around the transform-urls command, and log usage per run so a single batch cannot quietly run up a bill. Confirm which providers and models are configurable before you size the budget.
Weaver
How can I help you explore Laravel packages today?