DEV Community: Yuri Neves

Pensando em Yii3: como o framework se encaixa

Yuri Neves — Thu, 08 Oct 2026 04:27:23 +0000

Se você vem do Yii2, a primeira coisa que vai procurar no Yii3 é o Yii::$app. Ele não existe. Não tem objeto global da aplicação, não tem Controller base cheio de propriedades mágicas e não tem array de components.

Quando isso encaixa, o resto faz muito mais sentido. Este post é o modelo mental que eu queria ter antes de escrever qualquer código. Se preferir ir direto para a prática, o CRUD passo a passo usa tudo que está aqui.

É um conjunto de pacotes, não um framework monolítico

O Yii3 não é um repositório só. É uma coleção de pacotes yiisoft/* pequenos, e cada um faz uma coisa: yiisoft/router, yiisoft/di, yiisoft/db, yiisoft/validator, yiisoft/view e por aí vai.

Quem junta tudo num app funcionando é o template yiisoft/app. No meu projeto de CRUD, depois de adicionar os pacotes de banco e de formulário, são 49 pacotes yiisoft/* no vendor/. Você não precisa conhecer a maioria, mas ajuda saber que eles existem e que cada um funciona fora do Yii também.

Isso também quer dizer que você adiciona funcionalidades com composer require, e não ativando algo num arquivo de config gigante. Precisa de banco? composer require yiisoft/db-sqlite. Formulários? yiisoft/form-model. E a maioria dos pacotes traz a própria configuração, que é o próximo ponto.

A configuração é array PHP, mesclado de vários lugares

Toda a configuração fica em config/, dividida em grupos. O mapa dos grupos está em config/configuration.php:

'config-plugin' => [
    'params' => 'common/params.php',
    'params-web' => ['$params', 'web/params.php'],
    'params-console' => ['$params', 'console/params.php'],
    'di' => 'common/di/*.php',
    'di-web' => ['$di', 'web/di/*.php'],
    'di-console' => '$di',
    'routes' => 'common/routes.php',
    'bootstrap' => 'common/bootstrap.php',
    // ...
],

O grupo di é todo arquivo em config/common/di/, o di-web é isso mais os arquivos de config/web/di/, e assim por diante. O app web e o console leem grupos diferentes, e os ambientes (dev, prod, test) podem sobrescrever os params.

O detalhe importante é que os pacotes também trazem configuração. O yiisoft/session tem um config/di-web.php que liga FlashInterface a Flash. O yiisoft/db-migration registra os comandos migrate:* no config/params.php dele. Quando você instala um pacote, o yiisoft/config adiciona os arquivos dele ao "merge plan" (config/.merge-plan.php), e em tempo de execução eles são mesclados com os seus.

Então, depois de composer require yiisoft/db-migration, o ./yii migrate:up simplesmente existe, sem nenhuma linha escrita por você. Se você mexer no próprio configuration.php, rode composer yii-config-rebuild para atualizar o plano.

O container constrói tudo

Essa é a maior mudança em relação ao Yii2. No Yii3 você nunca busca um serviço em algum lugar: você pede no construtor, e o container de DI (yiisoft/di, PSR-11) entrega.

final readonly class PostRepository
{
    public function __construct(
        private ConnectionInterface $db,
    ) {}
}

Para uma classe concreta como PostRepository, você não escreve configuração nenhuma. O container lê o construtor, monta o que precisa e injeta. Isso é autowiring.

Você só precisa de uma definição quando o container não tem como adivinhar. Isso acontece com uma interface (qual implementação?) ou com um valor escalar (qual DSN?). Esta é a conexão de banco do CRUD, em config/common/di/db.php:

return [
    ConnectionInterface::class => static fn (Aliases $aliases, SchemaCache $schemaCache) => new Connection(
        new Driver('sqlite:' . $aliases->get('@runtime/database.sqlite')),
        $schemaCache,
    ),
];

Todas as classes do app dependem de ConnectionInterface, nunca de SQLite. Trocar para MySQL é mudar só esse arquivo.

Na prática, faço três perguntas quando escrevo uma classe:

Do que ela precisa? Isso vai no construtor.
É uma interface ou um valor? Então precisa de uma definição em config/*/di/.
Ela precisa saber de HTTP? Se não, fica fora de src/Web.

Uma requisição, do começo ao fim

Isto é o que acontece quando uma requisição chega no app:

O public/index.php cria um HttpApplicationRunner. O runner monta a configuração e o container, e entrega a requisição para a aplicação. A aplicação roda uma pilha de middlewares PSR-15 definida em config/web/di/application.php:

'withMiddlewares()' => [
    [
        ErrorCatcher::class,
        SessionMiddleware::class,
        CsrfTokenMiddleware::class,
        RequestCatcherMiddleware::class,
        Router::class,
    ],
],

Cada middleware recebe a requisição, pode fazer algo antes, chama o próximo e pode mexer na resposta depois. O ErrorCatcher é a camada mais externa, então qualquer exceção lançada lá dentro termina nele. O Router é o último: ele encontra a rota e chama a sua action. O que a action retorna volta pelas mesmas camadas, e o SapiEmitter envia para o navegador.

Middleware é como você se encaixa na requisição

Como tudo é middleware, adicionar comportamento em volta de uma requisição segue sempre a mesma ideia. Este aqui adiciona um header com o tempo de resposta:

final class ResponseTimeMiddleware implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $start = microtime(true);

        $response = $handler->handle($request);

        $ms = round((microtime(true) - $start) * 1000, 1);

        return $response->withHeader('X-Response-Time', $ms . 'ms');
    }
}

Você pode colocar na lista global ou ligar só em algumas rotas:

Group::create('/posts')
    ->middleware(ResponseTimeMiddleware::class)
    ->routes(/* ... */),

Autenticação, controle de acesso, CORS e rate limit funcionam todos assim. No meu blog, a área admin é um grupo de rotas com um middleware de permissão, e o grupo da API tem um middleware de token.

Actions são só callables

O template não tem controller base. A home é uma classe só, com __invoke():

final readonly class Action
{
    public function __construct(
        private WebViewRenderer $viewRenderer,
    ) {}

    public function __invoke(): ResponseInterface
    {
        return $this->viewRenderer->render(__DIR__ . '/template');
    }
}

A rota aponta para ela com ->action(Action::class). Se você prefere controllers com vários métodos, ->action([PostController::class, 'index']) também funciona, e foi o que usei no CRUD. Nos dois casos, a action recebe os serviços pelo construtor e retorna uma resposta PSR-7. Não precisa de classe base.

As coisas são imutáveis

Você vai ver muito método with*() no Yii3: $response->withHeader(), $viewRenderer->withViewPath(), $viewRenderer->withLayout(). Eles não alteram o objeto, retornam um novo.

// o $viewRenderer é compartilhado pelo app todo, então guardamos uma cópia nossa
$this->viewRenderer = $viewRenderer->withViewPath(__DIR__ . '/views');

O motivo é que os serviços são compartilhados. Se um controller mudasse o caminho das views no renderer compartilhado, todos os outros controllers seriam afetados. Com imutabilidade, isso não acontece. É também o que permite rodar o Yii3 em servidores de longa duração como o RoadRunner (existe o yiisoft/yii-runner-roadrunner), onde os mesmos objetos atendem muitas requisições.

Como eu organizo uma funcionalidade

O template já sugere um formato: src/Web/HomePage/Action.php com o template.php ao lado. Eu sigo essa ideia, agrupando por funcionalidade, e separo o que é web do que não é:

src/
  Post/
    PostRepository.php      # fala com o banco, não sabe nada de HTTP
  Web/
    Post/
      PostController.php    # HTTP: lê a requisição, devolve a resposta
      PostForm.php          # o que o formulário aceita + regras de validação
      views/
        index.php
        _form.php
  Migration/
    M261008033620CreatePostTable.php

Quando adiciono uma funcionalidade, costumo seguir esta ordem:

Uma migration para a tabela.
Um repository (ou service) em src/<Funcionalidade>, sem nada de HTTP.
Um form model, se tiver entrada do usuário.
Uma action ou controller em src/Web/<Funcionalidade>.
As rotas em config/common/routes.php.
As views ao lado do controller.
Uma definição em config/*/di/ só se algo novo for interface ou precisar de valores de config.

O repository não sabe que está sendo chamado de uma página web. A mesma classe pode ser usada depois num comando de console ou num endpoint de API, sem mudança. No meu blog, o mesmo PostRepository atende tanto as páginas do site quanto a API REST.

Vindo do Yii2

Resumindo: o que era implícito agora é explícito. Yii::$app->db vira um ConnectionInterface no construtor. Os components da config viram definições de DI. behaviors() e filtros viram middleware. Controllers não estendem nada, e o $this->render() vira um WebViewRenderer injetado. Active Record deixou de ser o padrão. Ele existe como pacote separado, mas o query builder resolve muita coisa.

No começo se digita mais. Em troca, você abre qualquer classe e vê tudo de que ela depende.

Próximo passo

Com isso em mente, o tutorial de CRUD deve parecer uma sequência de passos pequenos e óbvios: uma migration, um repository, um formulário, um controller, as rotas e as views. O código está em yurineves92/crud-yii3.

Se algo aqui não bate com a sua experiência com Yii3, me conta nos comentários. Também estou aprendendo.

Thinking in Yii3: How the Framework Fits Together

Yuri Neves — Thu, 08 Oct 2026 04:27:11 +0000

If you come from Yii2, the first thing you'll look for in Yii3 is Yii::$app. It isn't there. There's no global application object, no base Controller with a dozen magic properties, and no components array.

Once that clicks, the rest makes a lot more sense. This post is the mental model I'd want before writing any code. If you want to go straight to building something, the step-by-step CRUD uses everything explained here.

It's a set of packages, not one big framework

Yii3 isn't one repository. It's a collection of small yiisoft/* packages, and each one does a single job: yiisoft/router, yiisoft/di, yiisoft/db, yiisoft/validator, yiisoft/view and so on.

The yiisoft/app template is what wires them together into a working app. In my CRUD project, after adding the database and form packages, there are 49 yiisoft/* packages in vendor/. You don't have to know most of them, but it helps to know they exist and that each can be used outside Yii.

That also means you add features with composer require, not by enabling something in a big config file. You need a database? composer require yiisoft/db-sqlite. Forms? yiisoft/form-model. And most packages bring their own config, which leads to the next point.

Config is PHP arrays, merged from everywhere

All configuration lives in config/, split into groups. The map of groups is in config/configuration.php:

'config-plugin' => [
    'params' => 'common/params.php',
    'params-web' => ['$params', 'web/params.php'],
    'params-console' => ['$params', 'console/params.php'],
    'di' => 'common/di/*.php',
    'di-web' => ['$di', 'web/di/*.php'],
    'di-console' => '$di',
    'routes' => 'common/routes.php',
    'bootstrap' => 'common/bootstrap.php',
    // ...
],

di is every file in config/common/di/, di-web is that plus the files in config/web/di/, and so on. The web app and the console app read different groups, and the environments (dev, prod, test) can override params.

The important detail is that packages ship config too. yiisoft/session has a config/di-web.php that maps FlashInterface to Flash. yiisoft/db-migration registers the migrate:* console commands in its config/params.php. When you install a package, yiisoft/config adds its files to the "merge plan" (config/.merge-plan.php), and at runtime they are merged with yours.

So after composer require yiisoft/db-migration, ./yii migrate:up just exists, without any line written by you. If you edit configuration.php itself, run composer yii-config-rebuild to update the plan.

The container builds everything

This is the biggest change from Yii2. In Yii3 you never fetch a service from somewhere: you ask for it in the constructor and the DI container (yiisoft/di, PSR-11) passes it in.

final readonly class PostRepository
{
    public function __construct(
        private ConnectionInterface $db,
    ) {}
}

For a concrete class like PostRepository, you don't write any config. The container reads the constructor, builds what's needed and injects it. That's autowiring.

You only need a definition when the container can't guess. That happens with an interface (which implementation?) or a scalar (which DSN?). This is the database connection from the CRUD, in config/common/di/db.php:

return [
    ConnectionInterface::class => static fn (Aliases $aliases, SchemaCache $schemaCache) => new Connection(
        new Driver('sqlite:' . $aliases->get('@runtime/database.sqlite')),
        $schemaCache,
    ),
];

Every class in the app depends on ConnectionInterface, never on SQLite. Switching to MySQL means changing this file only.

In practice, there are three questions I ask when writing a class:

What does it need? Put that in the constructor.
Is it an interface or a value? Then it needs a definition in config/*/di/.
Does it need to know about HTTP? If not, keep it out of src/Web.

One request, start to finish

Here's what happens when a request hits the app:

public/index.php creates an HttpApplicationRunner. The runner builds the config and the container, then hands the request to the application. The application runs a stack of PSR-15 middleware defined in config/web/di/application.php:

'withMiddlewares()' => [
    [
        ErrorCatcher::class,
        SessionMiddleware::class,
        CsrfTokenMiddleware::class,
        RequestCatcherMiddleware::class,
        Router::class,
    ],
],

Each middleware gets the request, can do something before, calls the next one and can do something with the response after. ErrorCatcher is the outermost layer, so any exception thrown deeper ends up there. The Router is the last one: it finds the route and calls your action. Whatever your action returns travels back out through the same layers, and SapiEmitter sends it to the browser.

Middleware is how you plug into the request

Since everything is a middleware, adding behavior around a request is the same idea everywhere. This one adds a response time header:

final class ResponseTimeMiddleware implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $start = microtime(true);

        $response = $handler->handle($request);

        $ms = round((microtime(true) - $start) * 1000, 1);

        return $response->withHeader('X-Response-Time', $ms . 'ms');
    }
}

You can put it in the global list, or attach it only to some routes:

Group::create('/posts')
    ->middleware(ResponseTimeMiddleware::class)
    ->routes(/* ... */),

Authentication, access checks, CORS and rate limits all work this way. In my blog, the admin area is a route group with an access-check middleware, and the API group has a token middleware.

Actions are just callables

The template doesn't have a base controller. The home page is a single class with __invoke():

final readonly class Action
{
    public function __construct(
        private WebViewRenderer $viewRenderer,
    ) {}

    public function __invoke(): ResponseInterface
    {
        return $this->viewRenderer->render(__DIR__ . '/template');
    }
}

A route points to it with ->action(Action::class). If you prefer controllers with several methods, ->action([PostController::class, 'index']) works too, and that's what I used in the CRUD. Either way, the action receives services through the constructor and returns a PSR-7 response. No base class needed.

Things are immutable

You'll see a lot of with*() methods in Yii3: $response->withHeader(), $viewRenderer->withViewPath(), $viewRenderer->withLayout(). They don't change the object, they return a new one.

// $viewRenderer is shared by the whole app, so we keep our own copy
$this->viewRenderer = $viewRenderer->withViewPath(__DIR__ . '/views');

The reason is that services are shared. If one controller changed the view path on the shared renderer, every other controller would get it too. With immutability, that can't happen. It's also what lets Yii3 run on long-running servers like RoadRunner (there's yiisoft/yii-runner-roadrunner), where the same objects serve many requests.

How I organize a feature

The template already suggests a layout: src/Web/HomePage/Action.php with template.php next to it. I keep that idea, grouping by feature, and separate what is web from what isn't:

src/
  Post/
    PostRepository.php      # talks to the database, knows nothing about HTTP
  Web/
    Post/
      PostController.php    # HTTP: reads the request, returns a response
      PostForm.php          # what the form accepts + validation rules
      views/
        index.php
        _form.php
  Migration/
    M261008033620CreatePostTable.php

When I add a feature, I usually go in this order:

A migration for the table.
A repository (or service) in src/<Feature>, with no HTTP in it.
A form model, if there's user input.
An action or controller in src/Web/<Feature>.
Routes in config/common/routes.php.
Views next to the controller.
A definition in config/*/di/ only if something new is an interface or needs config values.

The repository doesn't know it's being called from a web page. The same class can be used from a console command or an API endpoint later without changes. In my blog, the same PostRepository serves both the site pages and the REST API.

Coming from Yii2

The short version: what was implicit is now explicit. Yii::$app->db becomes a ConnectionInterface in the constructor. components in the config become DI definitions. behaviors() and filters become middleware. Controllers don't extend anything, and $this->render() becomes an injected WebViewRenderer. Active Record isn't the default anymore. It exists as a separate package, but the query builder is enough for a lot of things.

It's more typing at first. In exchange, you can open any class and see everything it depends on.

With this in mind, the CRUD tutorial should read like a sequence of small, obvious steps: a migration, a repository, a form, a controller, routes and views. The code is at yurineves92/crud-yii3.

If something here didn't match your experience with Yii3, tell me in the comments. I'm still learning it too.

Building Your First CRUD App in Yii3: A Step-by-Step Guide for Beginners

Yuri Neves — Thu, 08 Oct 2026 04:23:31 +0000

I've been using Yii3 in a few side projects, and most "first CRUD" tutorials out there are still about Laravel. So here's one for Yii3.

If you come from Yii2, forget Yii::$app. Yii3 is PSR all the way down, and everything reaches your classes through the constructor. It's more explicit, and that actually makes it easier to follow, because nothing happens behind your back.

We'll build a small post manager with list, create, edit and delete. It uses SQLite and PHP's built-in server, so all you need is PHP 8.2+ (with pdo_sqlite) and Composer.

Step 1: Create the project

composer create-project yiisoft/app crud-app
cd crud-app
cp .env.example .env
./yii serve

Open http://127.0.0.1:8080 and you should see the Yii3 welcome page. On Windows, use yii.bat instead of ./yii.

Copying .env puts the app in dev mode, so errors come with a stack trace instead of a blank 500 page.

These are the folders we'll touch:

config/common/di/          # services, every file here is loaded
config/common/routes.php
config/console/params.php
src/                       # your code, namespace App\
runtime/                   # logs, cache and our SQLite file

Step 2: Install the database and form packages

The template doesn't ship with a database layer or forms, so we add them:

composer require yiisoft/db-sqlite yiisoft/db-migration yiisoft/cache yiisoft/form-model

db-sqlite gives you the connection and the query builder. db-migration adds the ./yii migrate:* commands. form-model brings form classes, validation and field widgets. cache is only there because the connection wants a schema cache.

Step 3: Configure the database connection

In Yii3, configuring something means telling the DI container how to build it. Create config/common/di/db.php:

<?php

declare(strict_types=1);

use Yiisoft\Aliases\Aliases;
use Yiisoft\Cache\ArrayCache;
use Yiisoft\Db\Cache\SchemaCache;
use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Db\Sqlite\Connection;
use Yiisoft\Db\Sqlite\Driver;

return [
    SchemaCache::class => [
        '__construct()' => [new ArrayCache()],
    ],

    ConnectionInterface::class => static fn (Aliases $aliases, SchemaCache $schemaCache) => new Connection(
        new Driver('sqlite:' . $aliases->get('@runtime/database.sqlite')),
        $schemaCache,
    ),
];

From now on, any class that asks for ConnectionInterface in its constructor gets this connection.

Then tell the migration tool where migrations live. In config/console/params.php:

<?php

declare(strict_types=1);

return [
    'yiisoft/yii-console' => [
        'commands' => require __DIR__ . '/commands.php',
    ],

    'yiisoft/db-migration' => [
        'newMigrationNamespace' => 'App\Migration',
        'sourceNamespaces' => ['App\Migration'],
    ],
];

Step 4: Create the `post` table

mkdir -p src/Migration
./yii migrate:create post --command=table --fields="title:string(200):notNull,body:text:notNull,created_at:datetime:notNull,updated_at:datetime:notNull"

The generator writes something like src/Migration/M261008033620CreatePostTable.php:

final class M261008033620CreatePostTable implements RevertibleMigrationInterface, TransactionalMigrationInterface
{
    public function up(MigrationBuilder $b): void
    {
        $columnBuilder = $b->columnBuilder();

        $b->createTable('post', [
            'id' => $columnBuilder::primaryKey(),
            'title' => $columnBuilder::string(200)->notNull(),
            'body' => $columnBuilder::text()->notNull(),
            'created_at' => $columnBuilder::datetime()->notNull(),
            'updated_at' => $columnBuilder::datetime()->notNull(),
        ]);
    }

    public function down(MigrationBuilder $b): void
    {
        $b->dropTable('post');
    }
}

Run it:

./yii migrate:up

Now runtime/database.sqlite exists, with the table in it.

Step 5: The repository

Yii3 doesn't push an ORM on you. For something this size, a small class using the query builder is enough. Create src/Post/PostRepository.php:

<?php

declare(strict_types=1);

namespace App\Post;

use Yiisoft\Db\Connection\ConnectionInterface;

final readonly class PostRepository
{
    public function __construct(
        private ConnectionInterface $db,
    ) {}

    /**
     * @return array[] Newest posts first.
     */
    public function findAll(): array
    {
        return $this->db->select()->from('post')->orderBy(['id' => SORT_DESC])->all();
    }

    public function findById(int $id): ?array
    {
        return $this->db->select()->from('post')->where(['id' => $id])->one();
    }

    public function create(string $title, string $body): int
    {
        $now = date('Y-m-d H:i:s');

        $this->db->createCommand()->insert('post', [
            'title' => $title,
            'body' => $body,
            'created_at' => $now,
            'updated_at' => $now,
        ])->execute();

        return (int) $this->db->getLastInsertId();
    }

    public function update(int $id, string $title, string $body): void
    {
        $this->db->createCommand()->update('post', [
            'title' => $title,
            'body' => $body,
            'updated_at' => date('Y-m-d H:i:s'),
        ], ['id' => $id])->execute();
    }

    public function delete(int $id): void
    {
        $this->db->createCommand()->delete('post', ['id' => $id])->execute();
    }
}

This class needs no config. The container sees ConnectionInterface in the constructor and passes the connection in. Values go through bound parameters, so SQL injection isn't a concern here. If you'd rather have Active Record, there's yiisoft/active-record.

Step 6: The form

The form is a class, and the validation rules are attributes on its properties. Create src/Web/Post/PostForm.php:

<?php

declare(strict_types=1);

namespace App\Web\Post;

use Yiisoft\FormModel\FormModel;
use Yiisoft\Validator\Rule\Length;
use Yiisoft\Validator\Rule\Required;

final class PostForm extends FormModel
{
    #[Required]
    #[Length(min: 3, max: 200, skipOnEmpty: true)]
    public string $title = '';

    #[Required]
    #[Length(min: 10, skipOnEmpty: true)]
    public string $body = '';
}

Without skipOnEmpty, an empty field would show two errors, "cannot be blank" and the length one.

Step 7: The controller

Create src/Web/Post/PostController.php:

<?php

declare(strict_types=1);

namespace App\Web\Post;

use App\Post\PostRepository;
use App\Web\NotFound\NotFoundHandler;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Yiisoft\FormModel\FormHydrator;
use Yiisoft\Http\Header;
use Yiisoft\Http\Status;
use Yiisoft\Router\HydratorAttribute\RouteArgument;
use Yiisoft\Router\UrlGeneratorInterface;
use Yiisoft\Session\Flash\FlashInterface;
use Yiisoft\Yii\View\Renderer\WebViewRenderer;

final readonly class PostController
{
    private WebViewRenderer $viewRenderer;

    public function __construct(
        WebViewRenderer $viewRenderer,
        private PostRepository $posts,
        private FormHydrator $formHydrator,
        private ResponseFactoryInterface $responseFactory,
        private UrlGeneratorInterface $urlGenerator,
        private FlashInterface $flash,
        private NotFoundHandler $notFoundHandler,
    ) {
        $this->viewRenderer = $viewRenderer->withViewPath(__DIR__ . '/views');
    }

    public function index(): ResponseInterface
    {
        return $this->viewRenderer->render('index', [
            'posts' => $this->posts->findAll(),
            'success' => $this->flash->get('success'),
        ]);
    }

    public function create(ServerRequestInterface $request): ResponseInterface
    {
        $form = new PostForm();

        if ($this->formHydrator->populateFromPostAndValidate($form, $request)) {
            $this->posts->create($form->title, $form->body);
            $this->flash->set('success', 'Post created!');

            return $this->redirectToIndex();
        }

        return $this->viewRenderer->render('create', ['form' => $form]);
    }

    public function edit(ServerRequestInterface $request, #[RouteArgument('id')] int $id): ResponseInterface
    {
        $post = $this->posts->findById($id);
        if ($post === null) {
            return $this->notFoundHandler->handle($request);
        }

        $form = new PostForm();
        $form->title = $post['title'];
        $form->body = $post['body'];

        if ($this->formHydrator->populateFromPostAndValidate($form, $request)) {
            $this->posts->update($id, $form->title, $form->body);
            $this->flash->set('success', 'Post updated!');

            return $this->redirectToIndex();
        }

        return $this->viewRenderer->render('edit', ['form' => $form, 'id' => $id]);
    }

    public function delete(#[RouteArgument('id')] int $id): ResponseInterface
    {
        $this->posts->delete($id);
        $this->flash->set('success', 'Post deleted.');

        return $this->redirectToIndex();
    }

    private function redirectToIndex(): ResponseInterface
    {
        return $this->responseFactory
            ->createResponse(Status::FOUND)
            ->withHeader(Header::LOCATION, $this->urlGenerator->generate('post/index'));
    }
}

create and edit handle both GET and POST. populateFromPostAndValidate() returns false when there's nothing posted yet or when validation fails, and in both cases we just render the form again. On a failed submit, the form already holds what the user typed plus the errors.

#[RouteArgument('id')] pulls {id} from the URL straight into the method as an int. The redirect is a plain PSR-7 response with a 302 status and a Location header.

Step 8: Routes

In config/common/routes.php, add a /posts group next to the home route:

<?php

declare(strict_types=1);

use App\Web;
use App\Web\Post\PostController;
use Yiisoft\Http\Method;
use Yiisoft\Router\Group;
use Yiisoft\Router\Route;

return [
    Group::create()
        ->routes(
            Route::get('/')
                ->action(Web\HomePage\Action::class)
                ->name('home'),

            Group::create('/posts')
                ->namePrefix('post/')
                ->routes(
                    Route::get('')
                        ->action([PostController::class, 'index'])
                        ->name('index'),
                    Route::methods([Method::GET, Method::POST], '/create')
                        ->action([PostController::class, 'create'])
                        ->name('create'),
                    Route::methods([Method::GET, Method::POST], '/{id:\d+}/edit')
                        ->action([PostController::class, 'edit'])
                        ->name('edit'),
                    Route::post('/{id:\d+}/delete')
                        ->action([PostController::class, 'delete'])
                        ->name('delete'),
                ),
        ),
];

{id:\d+} only matches numbers, so /posts/abc/edit is a 404 before it reaches the controller. Delete is POST only, so a GET to it returns 405.

Step 9: Views

Views are plain PHP. They go in src/Web/Post/views/.

index.php:

<?php

declare(strict_types=1);

use Yiisoft\Html\Html;

/**
 * @var Yiisoft\View\WebView $this
 * @var Yiisoft\Router\UrlGeneratorInterface $urlGenerator
 * @var Yiisoft\Yii\View\Renderer\Csrf $csrf
 * @var array[] $posts
 * @var string|null $success
 */

$this->setTitle('Posts');
?>

<div class="page-header">
    <h1>Posts</h1>
    <a class="btn" href="<?= $urlGenerator->generate('post/create') ?>">+ New post</a>
</div>

<?php if ($success): ?>
    <div class="alert"><?= Html::encode($success) ?></div>
<?php endif ?>

<?php if ($posts === []): ?>
    <p class="empty">No posts yet. Go write the first one!</p>
<?php else: ?>
    <table class="table">
        <thead>
        <tr>
            <th>#</th>
            <th>Title</th>
            <th>Updated</th>
            <th></th>
        </tr>
        </thead>
        <tbody>
        <?php foreach ($posts as $post): ?>
            <tr>
                <td><?= $post['id'] ?></td>
                <td><?= Html::encode($post['title']) ?></td>
                <td><?= Html::encode($post['updated_at']) ?></td>
                <td class="actions">
                    <a href="<?= $urlGenerator->generate('post/edit', ['id' => $post['id']]) ?>">Edit</a>
                    <?= Html::form()
                        ->post($urlGenerator->generate('post/delete', ['id' => $post['id']]))
                        ->csrf($csrf)
                        ->addAttributes(['onsubmit' => "return confirm('Delete this post?')"])
                        ->open() ?>
                        <button type="submit" class="link-danger">Delete</button>
                    <?= Html::form()->close() ?>
                </td>
            </tr>
        <?php endforeach ?>
        </tbody>
    </table>
<?php endif ?>

$urlGenerator and $csrf are available in every view, because the template config injects them. Html::encode() is there to escape whatever the user typed.

_form.php, shared by create and edit:

<?php

declare(strict_types=1);

use Yiisoft\FormModel\Field;
use Yiisoft\Html\Html;

/**
 * @var Yiisoft\Router\UrlGeneratorInterface $urlGenerator
 * @var Yiisoft\Yii\View\Renderer\Csrf $csrf
 * @var App\Web\Post\PostForm $form
 * @var string $action
 * @var string $submitLabel
 */
?>

<?= Html::form()->post($action)->csrf($csrf)->open() ?>

    <?= Field::text($form, 'title') ?>
    <?= Field::textarea($form, 'body')->addInputAttributes(['rows' => 8]) ?>

    <div class="form-actions">
        <?= Html::submitButton($submitLabel, ['class' => 'btn']) ?>
        <a href="<?= $urlGenerator->generate('post/index') ?>">Cancel</a>
    </div>

<?= Html::form()->close() ?>

Field::text($form, 'title') prints the label, the input with its current value, and the validation errors.

create.php and edit.php just set the title and include the form:

<?php // create.php

declare(strict_types=1);

/**
 * @var Yiisoft\View\WebView $this
 * @var Yiisoft\Router\UrlGeneratorInterface $urlGenerator
 * @var App\Web\Post\PostForm $form
 */

$this->setTitle('New post');
?>

<h1>New post</h1>

<?= $this->render('_form', [
    'form' => $form,
    'action' => $urlGenerator->generate('post/create'),
    'submitLabel' => 'Create',
]) ?>

<?php // edit.php

declare(strict_types=1);

/**
 * @var Yiisoft\View\WebView $this
 * @var Yiisoft\Router\UrlGeneratorInterface $urlGenerator
 * @var App\Web\Post\PostForm $form
 * @var int $id
 */

$this->setTitle('Edit post');
?>

<h1>Edit post #<?= $id ?></h1>

<?= $this->render('_form', [
    'form' => $form,
    'action' => $urlGenerator->generate('post/edit', ['id' => $id]),
    'submitLabel' => 'Save',
]) ?>

The header and footer come from the template layout in src/Web/Shared/Layout/Main/layout.php. For the styles, I added a few rules to the end of assets/main/site.css. They're in the repo if you want the same look.

Step 10: Try it

With ./yii serve running, go to http://127.0.0.1:8080/posts.

Submit a short title with an empty body, and the rules from PostForm kick in:

Edit reuses the same form, filled with the current data:

Delete asks for confirmation first:

Here's the path of one request, from the form submit to the redirect:

If a form ever returns 422, the _csrf field is missing. Every POST form needs ->csrf($csrf).

Next steps

From here, I'd add pagination with yiisoft/data and yiisoft/data-db, then login with yiisoft/user. Moving to MySQL or PostgreSQL only means changing config/common/di/db.php, and the repository stays the same.

The code is at yurineves92/crud-yii3.

If you've used Yii2, I'm curious what feels different to you in Yii3.

Seu primeiro CRUD com Yii3: passo a passo para iniciantes

Yuri Neves — Thu, 08 Oct 2026 04:23:16 +0000

Venho usando Yii3 em alguns projetos pessoais, e quase todo tutorial de "primeiro CRUD" que eu acho ainda é de Laravel. Então resolvi escrever um para Yii3.

Se você vem do Yii2, esquece o Yii::$app. O Yii3 é PSR de ponta a ponta, e tudo chega nas suas classes pelo construtor. É mais explícito, e isso deixa o código mais fácil de acompanhar, porque nada acontece escondido.

Vamos montar um gerenciador de posts simples, com listar, criar, editar e apagar. Ele usa SQLite e o servidor embutido do PHP, então você só precisa de PHP 8.2+ (com pdo_sqlite) e Composer.

Passo 1: Criar o projeto

composer create-project yiisoft/app crud-app
cd crud-app
cp .env.example .env
./yii serve

Abra http://127.0.0.1:8080 e você deve ver a página de boas-vindas do Yii3. No Windows, use yii.bat no lugar de ./yii.

Copiar o .env coloca o app em modo dev. Assim os erros aparecem com stack trace, em vez de uma página 500 genérica.

Estas são as pastas que vamos mexer:

config/common/di/          # serviços, todo arquivo aqui é carregado
config/common/routes.php
config/console/params.php
src/                       # seu código, namespace App\
runtime/                   # logs, cache e o arquivo do SQLite

Passo 2: Instalar os pacotes de banco e de formulário

O template não vem com camada de banco nem formulários, então a gente adiciona:

composer require yiisoft/db-sqlite yiisoft/db-migration yiisoft/cache yiisoft/form-model

O db-sqlite traz a conexão e o query builder. O db-migration adiciona os comandos ./yii migrate:*. O form-model traz as classes de formulário, a validação e os widgets de campo. O cache só está aí porque a conexão pede um cache de schema.

Passo 3: Configurar a conexão com o banco

No Yii3, configurar algo é dizer ao container de DI como construir aquilo. Crie config/common/di/db.php:

<?php

declare(strict_types=1);

use Yiisoft\Aliases\Aliases;
use Yiisoft\Cache\ArrayCache;
use Yiisoft\Db\Cache\SchemaCache;
use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Db\Sqlite\Connection;
use Yiisoft\Db\Sqlite\Driver;

return [
    SchemaCache::class => [
        '__construct()' => [new ArrayCache()],
    ],

    ConnectionInterface::class => static fn (Aliases $aliases, SchemaCache $schemaCache) => new Connection(
        new Driver('sqlite:' . $aliases->get('@runtime/database.sqlite')),
        $schemaCache,
    ),
];

A partir daqui, qualquer classe que pedir ConnectionInterface no construtor recebe essa conexão.

Depois, diga à ferramenta de migration onde elas ficam. Em config/console/params.php:

<?php

declare(strict_types=1);

return [
    'yiisoft/yii-console' => [
        'commands' => require __DIR__ . '/commands.php',
    ],

    'yiisoft/db-migration' => [
        'newMigrationNamespace' => 'App\Migration',
        'sourceNamespaces' => ['App\Migration'],
    ],
];

Passo 4: Criar a tabela `post`

mkdir -p src/Migration
./yii migrate:create post --command=table --fields="title:string(200):notNull,body:text:notNull,created_at:datetime:notNull,updated_at:datetime:notNull"

O gerador cria algo como src/Migration/M261008033620CreatePostTable.php:

final class M261008033620CreatePostTable implements RevertibleMigrationInterface, TransactionalMigrationInterface
{
    public function up(MigrationBuilder $b): void
    {
        $columnBuilder = $b->columnBuilder();

        $b->createTable('post', [
            'id' => $columnBuilder::primaryKey(),
            'title' => $columnBuilder::string(200)->notNull(),
            'body' => $columnBuilder::text()->notNull(),
            'created_at' => $columnBuilder::datetime()->notNull(),
            'updated_at' => $columnBuilder::datetime()->notNull(),
        ]);
    }

    public function down(MigrationBuilder $b): void
    {
        $b->dropTable('post');
    }
}

Rode a migration:

./yii migrate:up

Agora o runtime/database.sqlite existe, já com a tabela.

Passo 5: O repository

O Yii3 não te empurra um ORM. Para algo desse tamanho, uma classe pequena usando o query builder resolve. Crie src/Post/PostRepository.php:

<?php

declare(strict_types=1);

namespace App\Post;

use Yiisoft\Db\Connection\ConnectionInterface;

final readonly class PostRepository
{
    public function __construct(
        private ConnectionInterface $db,
    ) {}

    /**
     * @return array[] Newest posts first.
     */
    public function findAll(): array
    {
        return $this->db->select()->from('post')->orderBy(['id' => SORT_DESC])->all();
    }

    public function findById(int $id): ?array
    {
        return $this->db->select()->from('post')->where(['id' => $id])->one();
    }

    public function create(string $title, string $body): int
    {
        $now = date('Y-m-d H:i:s');

        $this->db->createCommand()->insert('post', [
            'title' => $title,
            'body' => $body,
            'created_at' => $now,
            'updated_at' => $now,
        ])->execute();

        return (int) $this->db->getLastInsertId();
    }

    public function update(int $id, string $title, string $body): void
    {
        $this->db->createCommand()->update('post', [
            'title' => $title,
            'body' => $body,
            'updated_at' => date('Y-m-d H:i:s'),
        ], ['id' => $id])->execute();
    }

    public function delete(int $id): void
    {
        $this->db->createCommand()->delete('post', ['id' => $id])->execute();
    }
}

Essa classe não precisa de configuração nenhuma. O container vê ConnectionInterface no construtor e entrega a conexão. Os valores vão como parâmetros (bind), então SQL injection não é problema aqui. Se você prefere Active Record, existe o yiisoft/active-record.

Passo 6: O formulário

O formulário é uma classe, e as regras de validação são atributos nas propriedades. Crie src/Web/Post/PostForm.php:

<?php

declare(strict_types=1);

namespace App\Web\Post;

use Yiisoft\FormModel\FormModel;
use Yiisoft\Validator\Rule\Length;
use Yiisoft\Validator\Rule\Required;

final class PostForm extends FormModel
{
    #[Required]
    #[Length(min: 3, max: 200, skipOnEmpty: true)]
    public string $title = '';

    #[Required]
    #[Length(min: 10, skipOnEmpty: true)]
    public string $body = '';
}

Sem o skipOnEmpty, um campo vazio mostraria dois erros: o "cannot be blank" e o de tamanho.

Passo 7: O controller

Crie src/Web/Post/PostController.php:

<?php

declare(strict_types=1);

namespace App\Web\Post;

use App\Post\PostRepository;
use App\Web\NotFound\NotFoundHandler;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Yiisoft\FormModel\FormHydrator;
use Yiisoft\Http\Header;
use Yiisoft\Http\Status;
use Yiisoft\Router\HydratorAttribute\RouteArgument;
use Yiisoft\Router\UrlGeneratorInterface;
use Yiisoft\Session\Flash\FlashInterface;
use Yiisoft\Yii\View\Renderer\WebViewRenderer;

final readonly class PostController
{
    private WebViewRenderer $viewRenderer;

    public function __construct(
        WebViewRenderer $viewRenderer,
        private PostRepository $posts,
        private FormHydrator $formHydrator,
        private ResponseFactoryInterface $responseFactory,
        private UrlGeneratorInterface $urlGenerator,
        private FlashInterface $flash,
        private NotFoundHandler $notFoundHandler,
    ) {
        $this->viewRenderer = $viewRenderer->withViewPath(__DIR__ . '/views');
    }

    public function index(): ResponseInterface
    {
        return $this->viewRenderer->render('index', [
            'posts' => $this->posts->findAll(),
            'success' => $this->flash->get('success'),
        ]);
    }

    public function create(ServerRequestInterface $request): ResponseInterface
    {
        $form = new PostForm();

        if ($this->formHydrator->populateFromPostAndValidate($form, $request)) {
            $this->posts->create($form->title, $form->body);
            $this->flash->set('success', 'Post created!');

            return $this->redirectToIndex();
        }

        return $this->viewRenderer->render('create', ['form' => $form]);
    }

    public function edit(ServerRequestInterface $request, #[RouteArgument('id')] int $id): ResponseInterface
    {
        $post = $this->posts->findById($id);
        if ($post === null) {
            return $this->notFoundHandler->handle($request);
        }

        $form = new PostForm();
        $form->title = $post['title'];
        $form->body = $post['body'];

        if ($this->formHydrator->populateFromPostAndValidate($form, $request)) {
            $this->posts->update($id, $form->title, $form->body);
            $this->flash->set('success', 'Post updated!');

            return $this->redirectToIndex();
        }

        return $this->viewRenderer->render('edit', ['form' => $form, 'id' => $id]);
    }

    public function delete(#[RouteArgument('id')] int $id): ResponseInterface
    {
        $this->posts->delete($id);
        $this->flash->set('success', 'Post deleted.');

        return $this->redirectToIndex();
    }

    private function redirectToIndex(): ResponseInterface
    {
        return $this->responseFactory
            ->createResponse(Status::FOUND)
            ->withHeader(Header::LOCATION, $this->urlGenerator->generate('post/index'));
    }
}

O create e o edit tratam GET e POST no mesmo método. O populateFromPostAndValidate() retorna false quando ainda não veio nada no POST ou quando a validação falha, e nos dois casos a gente só renderiza o formulário de novo. Num envio inválido, o formulário já volta com o que o usuário digitou e com os erros.

O #[RouteArgument('id')] pega o {id} da URL e entrega direto no método, já como int. O redirect é uma resposta PSR-7 comum, com status 302 e o header Location.

Passo 8: Rotas

Em config/common/routes.php, adicione um grupo /posts ao lado da rota da home:

<?php

declare(strict_types=1);

use App\Web;
use App\Web\Post\PostController;
use Yiisoft\Http\Method;
use Yiisoft\Router\Group;
use Yiisoft\Router\Route;

return [
    Group::create()
        ->routes(
            Route::get('/')
                ->action(Web\HomePage\Action::class)
                ->name('home'),

            Group::create('/posts')
                ->namePrefix('post/')
                ->routes(
                    Route::get('')
                        ->action([PostController::class, 'index'])
                        ->name('index'),
                    Route::methods([Method::GET, Method::POST], '/create')
                        ->action([PostController::class, 'create'])
                        ->name('create'),
                    Route::methods([Method::GET, Method::POST], '/{id:\d+}/edit')
                        ->action([PostController::class, 'edit'])
                        ->name('edit'),
                    Route::post('/{id:\d+}/delete')
                        ->action([PostController::class, 'delete'])
                        ->name('delete'),
                ),
        ),
];

O {id:\d+} só aceita números, então /posts/abc/edit vira 404 antes de chegar no controller. O delete só aceita POST, então um GET nele retorna 405.

Passo 9: Views

As views são PHP puro e ficam em src/Web/Post/views/.

index.php:

<?php

declare(strict_types=1);

use Yiisoft\Html\Html;

/**
 * @var Yiisoft\View\WebView $this
 * @var Yiisoft\Router\UrlGeneratorInterface $urlGenerator
 * @var Yiisoft\Yii\View\Renderer\Csrf $csrf
 * @var array[] $posts
 * @var string|null $success
 */

$this->setTitle('Posts');
?>

<div class="page-header">
    <h1>Posts</h1>
    <a class="btn" href="<?= $urlGenerator->generate('post/create') ?>">+ New post</a>
</div>

<?php if ($success): ?>
    <div class="alert"><?= Html::encode($success) ?></div>
<?php endif ?>

<?php if ($posts === []): ?>
    <p class="empty">No posts yet. Go write the first one!</p>
<?php else: ?>
    <table class="table">
        <thead>
        <tr>
            <th>#</th>
            <th>Title</th>
            <th>Updated</th>
            <th></th>
        </tr>
        </thead>
        <tbody>
        <?php foreach ($posts as $post): ?>
            <tr>
                <td><?= $post['id'] ?></td>
                <td><?= Html::encode($post['title']) ?></td>
                <td><?= Html::encode($post['updated_at']) ?></td>
                <td class="actions">
                    <a href="<?= $urlGenerator->generate('post/edit', ['id' => $post['id']]) ?>">Edit</a>
                    <?= Html::form()
                        ->post($urlGenerator->generate('post/delete', ['id' => $post['id']]))
                        ->csrf($csrf)
                        ->addAttributes(['onsubmit' => "return confirm('Delete this post?')"])
                        ->open() ?>
                        <button type="submit" class="link-danger">Delete</button>
                    <?= Html::form()->close() ?>
                </td>
            </tr>
        <?php endforeach ?>
        </tbody>
    </table>
<?php endif ?>

O $urlGenerator e o $csrf estão disponíveis em toda view, porque a config do template injeta os dois. O Html::encode() está ali para escapar o que o usuário digitou.

_form.php, usado pelo create e pelo edit:

<?php

declare(strict_types=1);

use Yiisoft\FormModel\Field;
use Yiisoft\Html\Html;

/**
 * @var Yiisoft\Router\UrlGeneratorInterface $urlGenerator
 * @var Yiisoft\Yii\View\Renderer\Csrf $csrf
 * @var App\Web\Post\PostForm $form
 * @var string $action
 * @var string $submitLabel
 */
?>

<?= Html::form()->post($action)->csrf($csrf)->open() ?>

    <?= Field::text($form, 'title') ?>
    <?= Field::textarea($form, 'body')->addInputAttributes(['rows' => 8]) ?>

    <div class="form-actions">
        <?= Html::submitButton($submitLabel, ['class' => 'btn']) ?>
        <a href="<?= $urlGenerator->generate('post/index') ?>">Cancel</a>
    </div>

<?= Html::form()->close() ?>

O Field::text($form, 'title') imprime o label, o input com o valor atual e os erros de validação.

O create.php e o edit.php só definem o título e incluem o formulário:

<?php // create.php

declare(strict_types=1);

/**
 * @var Yiisoft\View\WebView $this
 * @var Yiisoft\Router\UrlGeneratorInterface $urlGenerator
 * @var App\Web\Post\PostForm $form
 */

$this->setTitle('New post');
?>

<h1>New post</h1>

<?= $this->render('_form', [
    'form' => $form,
    'action' => $urlGenerator->generate('post/create'),
    'submitLabel' => 'Create',
]) ?>

<?php // edit.php

declare(strict_types=1);

/**
 * @var Yiisoft\View\WebView $this
 * @var Yiisoft\Router\UrlGeneratorInterface $urlGenerator
 * @var App\Web\Post\PostForm $form
 * @var int $id
 */

$this->setTitle('Edit post');
?>

<h1>Edit post #<?= $id ?></h1>

<?= $this->render('_form', [
    'form' => $form,
    'action' => $urlGenerator->generate('post/edit', ['id' => $id]),
    'submitLabel' => 'Save',
]) ?>

O cabeçalho e o rodapé vêm do layout do template, em src/Web/Shared/Layout/Main/layout.php. Para o visual, adicionei algumas regras no fim do assets/main/site.css. Elas estão no repositório, se quiser o mesmo resultado.

Passo 10: Testando

Com o ./yii serve rodando, acesse http://127.0.0.1:8080/posts.

Envie um título curto com o corpo vazio, e as regras do PostForm entram em ação:

A edição reaproveita o mesmo formulário, preenchido com os dados atuais:

O delete pede confirmação antes:

Este é o caminho de uma requisição, do envio do formulário até o redirect:

Se algum formulário retornar 422, está faltando o campo _csrf. Todo formulário POST precisa do ->csrf($csrf).

Próximos passos

Daqui, eu adicionaria paginação com yiisoft/data e yiisoft/data-db, e depois login com yiisoft/user. Trocar para MySQL ou PostgreSQL é só mudar o config/common/di/db.php, e o repository continua igual.

O código está em yurineves92/crud-yii3.

Se você já usou Yii2, fiquei curioso: o que parece mais diferente para você no Yii3?

DEV Community: Yuri Neves

Pensando em Yii3: como o framework se encaixa

É um conjunto de pacotes, não um framework monolítico

A configuração é array PHP, mesclado de vários lugares

O container constrói tudo

Uma requisição, do começo ao fim

Middleware é como você se encaixa na requisição

Actions são só callables

As coisas são imutáveis

Como eu organizo uma funcionalidade

Vindo do Yii2

Próximo passo

Thinking in Yii3: How the Framework Fits Together

It's a set of packages, not one big framework

Config is PHP arrays, merged from everywhere

The container builds everything

One request, start to finish

Middleware is how you plug into the request

Actions are just callables

Things are immutable

How I organize a feature

Coming from Yii2

Next

Building Your First CRUD App in Yii3: A Step-by-Step Guide for Beginners

Step 1: Create the project

Step 2: Install the database and form packages

Step 3: Configure the database connection

Step 4: Create the post table

Step 5: The repository

Step 6: The form

Step 7: The controller

Step 8: Routes

Step 9: Views

Step 10: Try it

Next steps

Seu primeiro CRUD com Yii3: passo a passo para iniciantes

Passo 1: Criar o projeto

Passo 2: Instalar os pacotes de banco e de formulário

Passo 3: Configurar a conexão com o banco

Passo 4: Criar a tabela post

Passo 5: O repository

Passo 6: O formulário

Passo 7: O controller

Passo 8: Rotas

Passo 9: Views

Passo 10: Testando

Próximos passos

Step 4: Create the `post` table

Passo 4: Criar a tabela `post`