Starter Kit for Laravel

Starter Kit vs SDK

Typically Headless CMS vendors provide an SDK that consists of a simple API wrapper for accessing your content. This is great for very simple use cases, but it doesn't provide the tools and structure needed to build a robust application.

Our Starter Kits are full featured frameworks in their own right, providing you a plethora of tools and features to help you build your application.

The Starter Kit for Laravel is capable of full Eloquent integration. We're not talking Eloquent-like, but actual Eloquent models that you can use to query your content.

Do I Need the Starter kit for Laravel?

Short answer: No.

Slightly longer answer: The typdy APIs are fully JSON:API compliant, and can be accessed from any language or framework that can make HTTP requests.

The Laravel Starter Kit is intended to provide a seamless experience for developers who are already familiar with Laravel and Eloquent.

Starter Kit for Laravel Features

The latest version of the Starter Kit for PHP provides the following features:

• A JSON:API compliant client for accessing your typdy content.
• Full Eloquent integration database synchronization and relationships.
• An alternative ORM-like experience, if Eloquent is not your thing.
• Zero configuration caching layer for improved performance.
• Optional storage drivers for greater application resilience and scalability.
• Custom webhook handlers for responding to typdy events.
• Authentication handler with auto-refreshing access tokens.
• Command line tools for scaffolding models and blueprints.
• And more!

Getting Started

The full installation and usage instructions for the Starter Kit for Larvel can be found in the GitHub repository: typdy/laravel-starter-kit

Installation

Install the Starter Kit using Composer:

composer require typdy/laravel-starter-kit

It's now time to configure the Starter Kit, so that it can connect to your typdy project and work with your project file structure.

Start by publishing the configuration file:

php artisan vendor:publish --provider="Typdy\StarterKit\Laravel\ServiceProvider"

Then head to config/tydpy.php to configure your integration:

<?php

use Typdy\StarterKit\Laravel\Storage\EloquentDriver;
use Typdy\StarterKit\Storage\RedisDriver;

return [
    'team' => 'my-team',
    'project' => 'my-team',

    'token' => env('TYPDY_TOKEN'),

    'repository_locations' => [
        'App\\Repositories' => app_path('Repositories'),
    ],

    'model_locations' => [
        'App\\Models' => app_path('Models'),
    ],

    'drivers' => [
        RedisDriver::class,
        EloquentDriver::class, // optional, for full Eloquent integration
    ],
];

First Steps

Next we need to create a model and a repository for our blueprint. Let's say we have a post blueprint and a latest-posts collection, we can use the scaffold command:

php artisan typdy:scaffold post --eloquent

This will generate a model called Post and a repository called LatestPostsRepository. They will be placed in the app/Models and app/Repositories directories that we specified in our configuration.

Here's the generated Eloquent model:

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Typdy\StarterKit\Attributes\Blueprint;
use Typdy\StarterKit\Laravel\Models\Concerns\UsesTypdy;
use Typdy\StarterKit\Models\Contracts\Construct;

#[Blueprint('post')]
final class Post extends Model implements Construct
{
    use UsesTypdy;
}

And the generated repository:

<?php

declare(strict_types=1);

namespace App\Repositories;

use App\Models\Post;
use Typdy\StarterKit\Attributes\Blueprint;
use Typdy\StarterKit\Attributes\Collection;
use Typdy\StarterKit\Models\Attributes\Relationship;
use Typdy\StarterKit\Repositories\Repository;

/**
 * @extends Repository<Post>
 */
#[Collection('posts')] #[Blueprint('post')]
final class PostsRepository extends Repository
{

}

Let's wire up some fields from our post blueprint:

<?php

declare(strict_types=1);

namespace App\Models;

use App\Models\Tag;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\MorphOne;
use Typdy\StarterKit\Attributes\Blueprint;
use Typdy\StarterKit\Laravel\Models\Concerns\UsesTypdy;
use Typdy\StarterKit\Laravel\Models\Media;
use Typdy\StarterKit\Models\Attributes\Relationship;
use Typdy\StarterKit\Models\Contracts\Construct;

#[Blueprint('post')]
final class Post extends Model implements Construct
{
    use UsesTypdy;

    /**
     * Fillable is required. It is used for generating migrations and deciding
     * which data to sync from typdy to the database.
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'title',
        'summary',
        'metaTitle',
        'metaDescription',
        'body',
    ];

    public function metaTitle(): Attribute
    {
        return Attribute::make(
            get: fn ($value) => $value ?: $this->title,
        );
    }

    public function metaDescription(): Attribute
    {
        return Attribute::make(
            get: fn ($value) => $value ?: $this->intro,
        );
    }

    /**
     * @return MorphOne<Media>
     */
    #[Relationship]
    public function coverImage(): MorphOne
    {
        return $this->hasOneMedia();
    }

    /**
     * @return BelongsToMany<Tag>
     */
    #[Relationship]
    public function tags(): BelongsToMany
    {
        return $this->belongsToMany(Tag::class)
    }
}

Fetching Content

At this point, we need some content to fetch. With the ORM-like models querying, fetching, and caching all take place in our repository call (e.g. $repo->all()). However, because we're using Eloquent, we need to copy data from typdy to the database. This is great for resilience, but does require some extra steps.

First we need some migrations:

php artian typdy:eloquent:migrations

This will scan your models and generate migrations. Of course, you can always manually create them if you prefer.

Now we need to run our migrations:

php artisan migrate

Now that we have a database, we should fill it with content:

php artisan typdy:eloquent:sync

Now we can query our data.

Querying Content

This is just Eloquent, so you can query your data as you would in any other project. If, however, you want to leverage more of the Starter Kit's caching features, then repositories are your friends.

The repository will try to fetch data from your configured RedisDriver before hitting the database. If the data isn't present in Redis, the repository will fetch it from the database and promote it up the driver stack, ensuring your next query is speedier.

<?php

use App\Repositories\PostsRepository;

$repo = new PostsRepository();

$posts = $repo->all([
    'query' => function ($query) {
        // this is just a regular Eloquent query
        $query->with('coverImage', 'tags')->latest();
    }
]);

foreach ($posts as $post) {

    echo $post->id . PHP_EOL;
    echo $post->identifier . PHP_EOL;

    echo $post->title . PHP_EOL;
    echo $post->summary . PHP_EOL;
    echo $post->metaTitle . PHP_EOL;
    echo $post->metaDescription . PHP_EOL;

    echo $post->created . PHP_EOL;
    echo $post->updated . PHP_EOL;

    if ($post->coverImage) {
        echo $post->coverImage->url . PHP_EOL;
    }

    foreach ($post->tags as $tag) {
        echo $tag->name . PHP_EOL;
    }
}

That's it! Your Laravel project is now connected to typdy, and you can start building your application using the Starter Kit for Laravel. For more advanced usage and features, please refer to the full documentation on GitHub.