## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require statamic/cms

Ensure you’re using Laravel 9+ and PHP 8.0+.

Publish Config:

php artisan vendor:publish --provider="Statamic\Providers\StatamicServiceProvider"

This generates config/statamic.php and config/statamic/fields.php.

First Use Case:
- Create a collection (php artisan statamic:collection blog) and a blueprint (php artisan statamic:blueprint blog/entry).
- Add a field (e.g., title, body) to the blueprint (resources/blueprints/collections/blog/entry.yaml).
- Publish a test entry via the Control Panel (CP) at /admin.

Key Starting Points

CP Access: /admin (credentials set in .env or config/statamic.php).
Documentation: statamic.dev (official docs are the best first resource).

CLI Commands:

php artisan statamic:install  # For fresh installs
php artisan statamic:blueprint  # Scaffold blueprints
php artisan statamic:field    # Add custom fields

Implementation Patterns

Core Workflows

1. Content Modeling

Collections: Organize content (e.g., blog, products) with YAML-based blueprints.

# resources/blueprints/collections/blog/entry.yaml
title: Entry
fields:
  - handle: title
    field:
      type: title
      display: Title
  - handle: body
    field:
      type: bard
      display: Content

Singletons: Single-page content (e.g., about) via php artisan statamic:singleton about.

2. Field Types

Built-in Fields: Use title, bard (WYSIWYG), assets, relationships, etc.

// In a blueprint or controller
use Statamic\Fields\Field;
$field = new Field('title', 'Title', 'title');

Custom Fields: Extend Statamic\Fields\Fieldtype:

namespace App\Fieldtypes;
use Statamic\Fields\Fieldtype;

class CustomField extends Fieldtype {
    public function field() {
        return new \Statamic\Fields\Field('custom_field', 'Custom Field', 'custom');
    }
}

'custom' => \App\Fieldtypes\CustomField::class,

3. Templates & Antlers

Antlers Syntax: Use {{ }} for dynamic content in templates (resources/views/).
```
<h1>{{ title }}</h1>
<div>{{ body }}</div>
```
Partial Templates: Reuse components with @include:
```
@include('partials/header')
```

Collections Loop:

@foreach(collections.blog.entries as entry)
    <article>
        <h2>{{ entry.title }}</h2>
        <p>{{ entry.body }}</p>
    </article>
@endforeach

4. Assets & Media

Uploads: Drag-and-drop via the CP (/admin/assets).
URLs: Access assets via {{ asset('filename.jpg') }} or programmatically:
```
$asset = asset('filename.jpg');
echo $asset->url();
```
Optimization: Use presets (e.g., php artisan statamic:preset):
```
# config/statamic/asset_containers/my_container/presets.yaml
thumbnails:
  width: 300
  height: 200
  fit: crop
```
- New in v6.19.0: Crop editor now shows dimensions for better precision.

5. Relationships

Link Entries: Use relationship fields in blueprints.

fields:
  - handle: author
    field:
      type: relationship
      display: Author
      collections: [authors]

Query Related Data:

@set author = entry.author.first()
<p>By {{ author.name }}</p>

6. Navigation

Nav Items: Define in config/statamic/nav.yaml:

items:
  - url: /blog
    title: Blog
    icon: blog

Dynamic Navs: Use nav in Antlers:
```
@nav
    @item('/blog', 'Blog')
    @item('/about', 'About')
@endnav
```
- Fixed in v6.19.0: nav:breadcrumbs now works correctly for multi-site setups.

7. Forms

CP Forms: Create forms in blueprints:

fields:
  - handle: contact_form
    field:
      type: form
      display: Contact Form
      submit_button: Send Message

Frontend Forms: Use statamic:form in views:
```
{{ form('contact') }}
    {{ csrf_field() }}
    {{ text('name') }}
    {{ email('email') }}
    {{ submit }}
{{ /form }}
```
- New in v6.19.0: Blade field templates are now supported for statamic-forms publish command.

8. Localization

Multi-Language: Enable in config/statamic/locales.php:

'locales' => [
    'en' => 'English',
    'es' => 'Spanish',
],

Localized Content: Use localized fields in blueprints:

fields:
  - handle: title
    field:
      type: title
      localized: true

9. API & GraphQL

REST API: Endpoints at /api/v1/collections/{handle}/entries.

GraphQL: Enable in config/statamic.php:

'graphql' => true,

Query entries:

query {
  entries(collection: "blog") {
    title
    body
  }
}

10. Customizing the CP

Themes: Override CP views in resources/views/vendor/statamic/cp/.
Widgets: Add to app/Widgets/ and register in config/statamic.php:
```
'widgets' => [
    \App\Widgets\CustomWidget::class,
],
```

CP Extensions: Use statamic:extend in service providers:

Statamic::extend(function () {
    Statamic::cp()->extend(function ($cp) {
        $cp->nav->add('custom', 'Custom', 'custom-icon');
    });
});

Blueprints Path Customization: Configure a custom base path for blueprints in config/statamic.php:
```
'blueprints' => [
    'path' => 'custom/blueprints/path',
],
```

Gotchas and Tips

Pitfalls

Caching Quirks:
- Clear caches after major changes:
```
php artisan statamic:clear-caches
```
- Use {{ cache }} in Antlers to control caching:
```
{{ cache(60) }}
    {{ expensive_query }}
{{ /cache }}
```
Field Validation:
- Validate fields in blueprints:
```
fields:
  - handle: email
    field:
      type: email
      validate:
        - required
        - email
```
- Custom validation requires extending Statamic\Fields\Fieldtype.
Asset Permissions:
- Ensure storage/ and public/ are writable:
```
chmod -R 775 storage/ public/
```
- Use php artisan storage:link for public assets.
Relationship Loops:
- Avoid circular relationships (e.g., A → B → A). Use lazy loading:
```
@set entry = entry.relationship.lazy()
```
Antlers Parsing:
- Escape variables with {{ 'raw' | raw }} to avoid parsing:
```
{{ '{{ title }}' | raw }}
```
- Use @set for dynamic variables:
```
@set dynamic_var = 'value'
{{ dynamic_var }}
```
CP Navigation:
- Trailing slashes in URLs can break CP nav active states. Configure in config/statamic.php:
```
'enforce_trailing_slashes' => false,
```

Cms Laravel Package