- How do I install adf-tools in a Laravel project?
- Run `composer require damienharper/adf-tools` in your Laravel project directory. The package supports PHP 8.1+ and Laravel 9+. No additional configuration is required unless you need service providers or facades, which can be registered manually in `config/app.php`.
- Can I convert Markdown to ADF format using this package?
- Yes, the package includes built-in conversion methods for Markdown to ADF and vice versa. Use the `Adf::fromMarkdown()` and `Adf::toMarkdown()` methods to handle these transformations. For HTML, use `Adf::fromHtml()` and `Adf::toHtml()`.
- Does adf-tools support custom ADF blocks or extensions?
- The package provides schema-aligned nodes for standard ADF blocks, but custom blocks require manual implementation. You can extend the base classes or use the `Adf::customBlock()` method to define non-standard structures. Always validate against Atlassian’s schema to ensure compatibility.
- What Laravel versions does adf-tools officially support?
- The package is compatible with Laravel 9+ and PHP 8.1+. While it may work on older versions, no official support or testing is provided. Always check the package’s `composer.json` for the latest requirements before upgrading.
- How do I validate ADF JSON against Atlassian’s schema?
- Use the `Adf::validate()` method to check if your ADF JSON adheres to Atlassian’s schema. This method throws exceptions for invalid structures, allowing you to handle errors gracefully. For custom validation, extend the validator class or use the built-in schema from Atlassian’s JSON Schema.
- Can I use adf-tools to generate Jira/Confluence documents programmatically?
- Yes, the package is designed for programmatic document generation. Build ADF structures in PHP, then export them to JSON for use in Jira or Confluence APIs. However, note that this package does not include Atlassian API SDK integration—you’ll need to handle API calls separately.
- What are the performance considerations for large ADF documents?
- Large ADF documents may consume significant memory during parsing or generation. Implement chunked processing or caching for performance-critical applications. The package itself does not enforce async processing, so you may need to integrate Laravel queues or jobs for scalability.
- Are there alternatives to adf-tools for Laravel ADF manipulation?
- If you need a more feature-rich solution, consider the official Atlassian PHP SDK or community packages like `atlassian-php-sdk`. However, these may require additional setup. For lightweight ADF parsing/generation, `adf-tools` remains a solid choice with no external dependencies.
- How do I handle malformed ADF JSON in production?
- Use try-catch blocks around `Adf::fromArray()` or `Adf::fromJson()` to gracefully handle parsing errors. The 1.2.1 release includes fixes for edge cases (e.g., unknown block types), but always validate inputs and log errors for debugging. Consider failing fast or degrading to HTML/Markdown if ADF parsing fails.
- Does adf-tools support real-time collaboration or live sync with Atlassian?
- No, this package is a low-level tool for ADF parsing and generation. Real-time collaboration or live sync requires Atlassian’s API SDK or webhooks. Use `adf-tools` to prepare ADF payloads, then integrate with the Atlassian API for live updates.