Yii3 - How to start

Tutorials

3.0

# Intro

In Yii3 it is not as easy to start as it was with Yii2. You have to install and configure basic things on your own. Yii3 uses the modern approach based on independent packages and dependency injection, but it makes it harder for newcomers. I am here to show all how I did it.

> ## Git
 
 
All themy code is available in my new [GitHub repositoryies:
 
- [Yii3 API demo](https://github.com/rackycz/yii3api). (yii3api) - May be dropped in the future as `yii3web` offers more)
 
- [Yii3 WEB demo](https://github.com/rackycz/yii3web) (yii3web) - I think I will use this one more
 
 
I will be using it as a boiler-plate for my future projects so it should be always up-to-date and working. ## Docker
 
 
Instead of installing local WAMP- or XAMPP-server I will be using Docker. Do not forget about a modern IDE like PhpStorm, which comes bundled with all you will ever need.Check [this YouTube video](https://www.youtube.com/watch?v=TqMXzEK0nsA) for explanation


 
## construct() and invoke()
 
It may be confusing that some classes contain both methods if t135 packages by Yii
 
 
The Yii team split the functionalities if Yii3 into 135 packages which you should check in advance to know what is available. They are listed [here](https://www.yiiframework.com/status/3.0) or the same is also [he reader does not have experiences with invoking. Just like me a few days ago. ](https://www.yiiframework.com/doc/api/3.0).
 
 
For example [login](https://github.com/yiisoft/user) and [RBAC](https://github.com/yiisoft/rbac), which can be stored in [DB](https://github.com/yiisoft/rbac-db) or in [PHP files](https://github.com/yiisoft/rbac-php/). And many more like "active-record" (which is now finished), "form-model" or "boostrap5".
 
 
## invoke()
 
The `__invoke()` public method is called when you call the **instance** as a method. Like this:(Therefore the constructor was already executed)

```php```

Note that "property promotion" should be only used in `__construct()` just like the dependency injection.
 
 
 
## Hash annotations for class attributes
 
PHP 8 introduces annotations like this (not only for class attributes):
 
 
- `#[Column(type: 'primary')]`
 
- `#[Column(type: 'string(255)', nullable: true)]`
 
- `#[Entity(repository: UserRepository::class)]`
 
- `#[ManyToMany(target: Role::class, through: UserRole::class)]`
 
 
They should replace the original DocBlock annotatinos and provide more new functionalities.
 
 
Learn what they mean and how they are used by Yii3. To me this is a brand new topic as well.
 
 
 
# Yii3 - How to start
 
 
Yii3 offers more basic applications: Web, Console, API. I will be using the API application:
 
- https://github.com/yiisoft/app-api
 
- Other apps are linked on the page
 
 
Clone it like this:
 
- git clone https://github.com/yiisoft/app-api.git yii3api
 
 
.. and follow the **docker** instructions in the documentation.
 
 
If you don't have Docker, I recommend installing the **latest** version of Docker Desktop:
 
- https://docs.docker.com/get-started/introduction/get-docker-desktop/
 
 
## Running the demo application
 
 
You may be surprised that docker-compose.yml is missing in the root. Instead the "make" commands are prepared.
 
If you run both basic commands as mentioned in the documentation:
 
 
- make composer update
 
- make up
 
 
... then the web will be available on URL
 
- http://localhost:80
 
- If run via browser, XML is returned
 
- If run via Postman or Ajax, JSON is returned
 
 
If you want to modify the data that was returned by the endpoint, just open the action-class `src/Api/IndexAction.php` and add one more element to the returned array.## Theory around __invoke():
 
- If a class implements the `__invoke()` method it is a `callable-` or `invokable-object`.
 
- Its instance can be used as an anonymous function, callable or closure.
 
- `__invoke()` implements the main (or the only) functionality of the object.
 
 
- Why not to use `$instance->myMethod()` instead? You would need to implement an API and others would have to know it. Calling `$instance()` is a "universal anonymous API". Plus modern middleware or handlers often need to be passed as "callables".
 
- Usual anonymous functions can only do a simple task. When you use `$instance()`, you are backed with a large object which can do much more. It can also use traits, state or OOP benefits.
 
- Method `__invoke($a ,$b)` can take input parameters. But the application must know about them, which brings me back to interfaces. I am confused a little. So the invoke-params should probably be mostly provided by the DI I guess.
 
- But you still can use method instead of invokation. For example in file `config/common/routes.php` you can use both:
 
  - `->action(Web\HomePage\Action::class)` // \__invoke() needed
 
  - `->action([Web\HomePage\Action::class, 'run'])`
 
- Invokable objects are often used for middleware as it fits naturally into dispatcher and pipeline systems. Middleware can then be stateful. But the same aplies to interface-based approaches, you only need to specify the method.
 
 
Summary:
 
 
Whenever a method requires a **callable** as the input parameter, you can supply "named function", "anonymous function" or  "invokable object". It is up to you what you pick.
 
 
 
## Hash annotations for class attributes
 
PHP 8 introduces annotations like this (not only for class attributes):
 
 
- `#[Column(type: 'primary')]`
 
- `#[Column(type: 'string(255)', nullable: true)]`
 
- `#[Entity(repository: UserRepository::class)]`
 
- `#[ManyToMany(target: Role::class, through: UserRole::class)]`
 
 
They should replace the original DocBlock annotatinos and provide more new functionalities.
 
 
Learn what they mean and how they are used by Yii3. To me this is a brand new topic as well.
 
 
 
# Yii3 - How to start
 
 
Yii3 offers more basic applications: Web, Console, API. I will be using the API application:
 
- https://github.com/yiisoft/app-api
 
- Other apps are linked on the page
 
 
Clone it like this:
 
- git clone https://github.com/yiisoft/app-api.git yii3api
 
 
.. and follow the **docker** instructions in the documentation.
 
 
If you don't have Docker, I recommend installing the **latest** version of Docker Desktop:
 
- https://docs.docker.com/get-started/introduction/get-docker-desktop/
 
 
## Running the demo application
 
 
You may be surprised that docker-compose.yml is missing in the root. Instead the "make up" and "make down" commands are prepared.
 
If you run both basic commands as mentioned in the documentation:
 
 
- make composer update
 
- make up
 
 
... then the web will be available on URL
 
- http://localhost:80
 
- If run via browser, XML is returned
 
- If run via Postman or Ajax, JSON is returned
 
 
If you want to modify the data that was returned by the endpoint, just open the action-class `src/Api/IndexAction.php` and add one more element to the returned array.
 
 
> You may be missing 'docker compose stop' or 'make stop', because 'make down' removes your containers and drops your DB. In that case you can add it to the Makefile in the root (see below). If you then type 'make help' you will see the new command. 
 
 
```sh
 
ifeq ($(PRIMARY_GOAL),stop)
 
stop: ## Stop the dev environment
 
$(DOCKER_COMPOSE_DEV) stop
 
endif
 
```

## Adding DB into your projectNext we also need an algorithm that will enforce these tokens in each request, will validate and refresh them and will restrict access only to endpoints that the user can use. This is a bigger topic for later. It may be covered by the package https://github.com/yiisoft/auth/ which offers "HTTP bearer authentication".

## UI
 
 
**Pjax**
 
 
Pjax does not exist any more, but you can use [HTMX](https://htmx.org/docs/#introduction) instead:
 
 
```
 
<script src="htmx.min.js"></script>
 
```
 
 
Your action:
 
 
 
```
 
<?php
 
declare(strict_types=1);
 
namespace App\Web\HomePage;
 
use Psr\Http\Message\ResponseFactoryInterface;
 
use Psr\Http\Message\ResponseInterface;
 
final readonly class Htmx
 
{
 
    public function __invoke(
 
        ResponseFactoryInterface $responseFactory
 
    ): ResponseInterface
 
    {
 
        $response = $responseFactory->createResponse();
 
        $response
 
            ->getBody()
 
            ->write('You are at homepage.<div id="id2">Welcome</div>');
 
        return $response;
 
    }
 
}
 
```
 
 
And then a simple HTML
 
 
```
 
<h2>HTMX test</h2>
 
<div id="htmx">
 
    <p>This is the original text</p>
 
</div>
 
<button data-hx-get="/htmx"
 
        data-hx-trigger="click"
 
        data-hx-target="#htmx"
 
        data-hx-select="#id2"
 
        data-hx-swap="innerHTML">
 
    Click me (and watch the traffic in devtools)
 
</button>
 
```
 
 
**JS client - Installable Vuejs3 PWA** If you create a REST API you may be interested in a JS frontend that will communicate with it using Ajax. Below you can peek into my very simple VueJS3 attempt. It is an installable PWA application that works in offline mode (=1 data transfer per day, not on every mouse click) and is meant for situations when customer does not have wifi everywhere. See my [Gitlab](https://gitlab.com/radin.cerny/vuejs3-pwa-demo-plus).