Getting Started

Minimal Steps to Begin

Installation
- Require via Composer:
```
composer require craftcms/cms
```
- Follow the official installation guide to set up the environment, database, and initial configuration.

First Use Case: Creating a Basic Entry

Define an Entry Type and Section in the Control Panel (Settings > Sections).

Create a Twig template in templates/_entry.twig to render entries:

{% extends "_layouts/base" %}

{% block content %}
    <h1>{{ entry.title }}</h1>
    {{ entry.body }}
{% endblock %}

Use the Element API to fetch entries in a controller or template:

{% set entries = craft.entries.section('blog').all() %}
{% for entry in entries %}
    {{ entry.title }}
{% endfor %}

Key First Look
- Control Panel: Navigate to http://your-site.com/admin to manage content.
- Twig Debug: Enable in config/app.php to inspect variables:
```
'devMode' => true,
```

Implementation Patterns

Core Workflows

1. Content Modeling

Fields: Use built-in fields (e.g., PlainText, Matrix, Assets) or create custom fields via plugins.

// Example: Adding a custom field to an entry type
Event::on(
    EntryType::class,
    EntryType::EVENT_DEFINE_FIELDS,
    function (DefineFieldsEvent $event) {
        $event->fields['customField'] = Field::make('plainText')
            ->label('Custom Field');
    }
);

Sections: Define structured content hierarchies (e.g., Channel, Single, Structure).

2. Templating

Twig Extensions: Extend Twig with custom functions/filters:

// config/app.php
'components' => [
    'view' => [
        'twig' => [
            'extension' => [
                \App\Twig\CustomExtension::class,
            ],
        ],
    ],
];

// App/Twig/CustomExtension.php
class CustomExtension extends \Twig\Extension\AbstractExtension
{
    public function getFunctions()
    {
        return [
            new \Twig\TwigFunction('customFunction', [$this, 'customFunction']),
        ];
    }

    public function customFunction($arg)
    {
        return "Processed: " . $arg;
    }
}

Template Inheritance: Use _layouts/ for shared layouts and _includes/ for reusable components.

3. Element Queries

Eager Loading: Optimize queries with with and relations:

{% set entry = craft.entries()
    .section('blog')
    .title('First Post')
    .with(['author', 'categories'])
    .one() %}

Criteria API: Build complex queries in PHP:

$entries = Entry::find()
    ->section('blog')
    ->postDate('>= ' . date('Y-m-d'))
    ->orderBy(['postDate' => SORT_DESC])
    ->all();

4. GraphQL

Enable in config/app.php:
```
'enableGraphQl' => true,
```

Query entries via GraphQL:

query {
  entries(section: "blog") {
    title
    body
    author {
      name
    }
  }
}

5. Plugins

Extend Functionality: Create plugins for reusable logic (e.g., custom fields, modules).
- Scaffold a plugin:
```
php craft create-plugin MyPlugin
```
- Register services, events, and CP routes in MyPlugin.php.

6. Assets & Media

Transforms: Generate image variants:

{% set image = entry.heroImage.one() %}
<img src="{{ image.getUrl('thumb') }}" alt="{{ image.title }}">

Volumes: Manage storage locations (e.g., local, S3) via Settings > Assets.

7. Localization

Sites: Configure multi-site setups in config/sites.php.
Translations: Use craft i18n for content translations.

8. Headless Mode

API Routes: Serve content via REST/GraphQL endpoints:

// config/routes.php
return [
    'api/v1/entries' => \App\controllers\EntriesController::class,
];

Decoupled Frontends: Use Craft as a backend for React/Vue apps.

Integration Tips

Laravel Integration
- Craft is a standalone app but can coexist with Laravel via:
  - Shared vendor/ directory.
  - Custom routes/controllers in web.php.
- Example: Proxy requests to Craft:
```
Route::get('/api/craft/{path}', function ($path) {
    return app('craft')->getRequest()->setPathInfo('/api/' . $path)->run();
});
```

Queue System

Use Craft’s queue for background tasks (e.g., asset transforms):
```
php craft queue/run
```

Custom jobs:

class MyJob extends \craft\queue\BaseJob
{
    public function execute($queue)
    {
        // Task logic
    }
}

Security
- Permissions: Leverage Craft’s RBAC system (Settings > Users > Permissions).
- CSRF/XSS: Craft handles most protections; validate inputs with craft\helpers\Html::encode().

Performance

Caching: Use craft.app.cache:

$cache = Craft::$app->getCache();
$cache->set('key', 'value', 3600);

Asset Indexing: Disable for large volumes:
```
'assetIndexingEnabled' => false,
```

Gotchas and Tips

Pitfalls

Runtime Path Issues
- Problem: Overriding runtimePath in config/app.php may not work due to #18936.
- Fix: Ensure the directory is writable and explicitly set:
```
'runtimePath' => __DIR__ . '/../runtime',
```
Entry Post Dates
- Problem: Post dates are null until the entry is saved as enabled (#18642).
- Fix: Set manually in code or via UI:
```
$entry->postDate = time();
```
Matrix Field Quirks
- Problem: Collapsed blocks may show generic "Entry [ID]" labels if the entry type lacks a UI label (#18484).
- Fix: Configure uiLabel in the entry type settings.
GraphQL Sandboxing
- Problem: dataUrl() is disabled by default in sandboxed environments.
- Fix: Whitelist in config/graphql.php:
```
'sandboxed' => [
    'allowedFunctions' => ['dataUrl'],
],
```
Element Deletion
- Problem: Deleting elements with relationships may fail silently.
- Fix: Use the deletion modal or check for dependencies:
```
if ($element->getContent()->getRelations()) {
    Craft::$app->getSession()->setErrorCms('Element has dependencies.');
}
```
Twig Debugging
- Problem: {{ dump() }} may not work in production due to devMode.
- Fix: Use {{ craft.app.config.devMode ? dump(_context) : '' }} or enable debug toolbar.
Asset Alternative Text
- Problem: Replacing assets may not preserve alternative text (#18713).
- Fix: Manually set after replacement:
```
$asset->alternativeText = $oldAsset->alternativeText;
```
Element Indexes
- Problem: Horizontal scroll bars may appear during loading (#18870).
- Fix: Update Craft or override CSS:
```
.element-index {
    overflow-x: hidden !important;
}
```

Cms Laravel Package