yiisoft / app

Yii3 application template

Yii Application Template

Application template for Yii 3 is best for rapidly creating projects.

Requirements

• PHP 8.1 or higher.

Installation

If you do not have Composer, you may install it by following the instructions at getcomposer.org.

You can then install this project template using the following command:

composer create-project --prefer-dist --stability=dev yiisoft/app <your project>

In order to launch development web server run:

composer run serve

Now you should be able to access the application through the URL printed to console. Usually it is http://localhost:8080.

Directory structure

The application template has the following structure:

config/             Configuration files.
docs/               Documentation.
public/             Files publically accessible from the Internet.
    assets/         Published assets.
    index.php       Entry script.
resources/          Application resources.
    assets/         Asset bundle resources.
    layout/         Layout view templates.
    view/           View templates.
runtime/            Files generated during runtime.
src/                Application source code.
    Asset/          Asset bundle definitions.
    Controller/     Web controller classes.
    Command/        Console commands.
tests/              A set of Codeception tests for the application.
vendor/             Installed Composer packages.

Configuration

You can find configuration in config directory. There are multiple configs, and the most interesting is params.php. Below there are details about its sections:

Application Services

There are multiple pre-configured application services.

Aliases

'yiisoft/aliases' => [
    'aliases' => [
        // standard directory aliases
        '@root' => dirname(__DIR__),
        '@assets' => '@root/public/assets',
        '@assetsUrl' => '/assets',
        '@npm' => '@root/node_modules',
        '@public' => '@root/public',
        '@resources' => '@root/resources',
        '@runtime' => '@root/runtime',
        '@views' => '@root/resources/views'
    ],
],

See "Aliases" in the guide.

Cache

'yiisoft/cache-file' => [
    'file-cache' => [
        // cache directory path
        'path' => '@runtime/cache'
    ],
],

Log Target File

use Psr\Log\LogLevel;

'yiisoft/log-target-file' => [
    'file-target' => [
        // route directory file log
        'file' => '@runtime/logs/app.log',
        // levels logs target
        'levels' => [
            LogLevel::EMERGENCY,
            LogLevel::ERROR,
            LogLevel::WARNING,
            LogLevel::INFO,
            LogLevel::DEBUG,
        ],
    ],
    'file-rotator' => [
        // maximum file size, in kilo-bytes. Defaults to 10240, meaning 10MB.
        'maxfilesize' => 10,
        // number of files used for rotation. Defaults to 5.
        'maxfiles' => 5,
        // the permission to be set for newly created files.
        'filemode' => null,
        // Whether to rotate files by copy and truncate in contrast to rotation by renaming files.
        'rotatebycopy' => null
    ],
],

See "Logging" in the guide.

Session

'yiisoft/session' => [
    'session' => [
        // options for cookies
        'options' => ['cookie_secure' => 0],
        // session handler
        'handler' => null
    ],
],

View

'yiisoft/view' => [
    // Custom parameters that are shared among view templates.
    'defaultParameters' => [
        'applicationParameters' => 'App\ApplicationParameters',
        'assetManager' => 'Yiisoft\Assets\AssetManager',
    ],
    'theme' => [
        // Apply pathMap example: ['@resources/layout' => '@resources/theme'] in yiisoft/app
        // Apply pathMap example: ['@resources/layout' => '@modulealiases/theme'] in module
        'pathMap' => [],
        'basePath' => '',
        'baseUrl' => '',
    ],    
],

Yii Debug

'yiisoft/yii-debug' => [
    // enabled/disabled debugger
    'enabled' => true
],

Application Layout Parameters

'app' => [
    'charset' => 'UTF-8',
    'language' => 'en',
    'name' => 'My Project',
],

Testing

The template comes with ready to use Codeception configuration. In order to execute tests run:

composer run serve > ./runtime/yii.log 2>&1 &
vendor/bin/codecept run

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

Support the project

Follow updates

License

The Yii Application Template is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

app's Issues

Composer installation error

/var/www$ composer create-project --prefer-dist --stability=dev yiisoft/app app
Creating a "yiisoft/app" project at "./app"
Installing yiisoft/app (1.0.x-dev 9b4ba45)

• Downloading yiisoft/app (dev-master 9b4ba45)
• Installing yiisoft/app (dev-master 9b4ba45): Extracting archive
  Created project in /var/www/app
  Loading composer repositories with package information
  Updating dependencies
  Your requirements could not be resolved to an installable set of packages.

Problem 1
- Root composer.json requires yiisoft/files ^1.0 -> satisfiable by yiisoft/files[1.0.0].
- yiisoft/yii-view dev-master requires yiisoft/csrf ^1.0 -> satisfiable by yiisoft/csrf[1.0.0, 1.0.1, 1.0.2].
- yiisoft/csrf[1.0.0, ..., 1.0.2] require yiisoft/security ^1.0 -> satisfiable by yiisoft/security[1.0.0].
- yiisoft/security 1.0.0 requires yiisoft/strings ^1.0 -> satisfiable by yiisoft/strings[1.0.0, 1.0.1, 1.1.0, 1.2.0].
- You can only install one version of a package, so only one of these can be installed: yiisoft/strings[1.0.0, 1.0.1, 1.1.0, 1.2.0, 2.0.0].
- yiisoft/yii-view 3.0.x-dev is an alias of yiisoft/yii-view dev-master and thus requires it to be installed too.
- yiisoft/files 1.0.0 requires yiisoft/strings ^2.0 -> satisfiable by yiisoft/strings[2.0.0].
- Root composer.json requires yiisoft/yii-view ^3.0@dev -> satisfiable by yiisoft/yii-view[3.0.x-dev (alias of dev-master)].

Remove SubFolder middleware from pipeline

I think we should remove the SubFolder middleware from pipeline.
Its ok for yiisoft/yii-demo but ok't for yiisoft/app

app/src/Provider/MiddlewareProvider.php

Line 24 in b401b32

->addMiddleware($container->get(SubFolder::class))

Configuration wizard

A console configuration wizard will be great to have. For example:

- Do you want database? Y
- Cycle or DB? DB
- Which server to connect to? localhost
- What is login? root
- What's password? superpassword

will install db package and configure it.

Remove null condition for title in layout/main.php

Yiisoft\View::getTitle() return as string, can never contain null

Move SessionMiddleware, CsrfMiddleware, ErrorCatcher Middleware to routes

It is proposed by SessionMiddleware, CsrfMiddleware, ErrorCatcher to transfer MiddlewareProvider.php to routes.php since the application can have REST API and other APIs for which these Middleware are not required.

CsrfMiddleware and CsrfAwareActionInterface

CsrfMiddleware is currently running for all requests. However, this functionality is sometimes not required, or a separate implementation is required for individual endpoints that process external requests as API.

Magento has a CsrfAwareActionInterface endpoint interface. If implemented, the endpoint checks the Csrf itself, otherwise the Csrf is checked by Magento. You need to do something like this.

Ability to override routes declared by packages in the app

Currently, the routes located in config/routes.php, but that shouldn't be there.

Do not use constants in index.php

We do not really need these and can use env variables instead.

Psr\Log\LoggerInterface not found

What steps will reproduce the problem?

modify vendor directory, then

in index.php
`$config = new Config(
new ConfigPaths($rootPath,'config','../vendor'),
);

// Run HTTP application runner
$runner = new HttpApplicationRunner($rootPath, $_ENV['YII_DEBUG'], $_ENV['YII_ENV']);
$runner->withConfig($config)->run();`

throwable: Yiisoft\Di\NotFoundException: No definition or class found or resolvable for "Psr\Log\LoggerInterface" while building "Yiisoft\ErrorHandler\ErrorHandler" -> "Psr\Log\LoggerInterface". in ****\vendor\yiisoft\di\src\Container.php:542
Stack trace:
#0 ****\vendor\yiisoft\di\src\Container.php(503): Yiisoft\Di\Container->buildInternal()
#1 ****\vendor\yiisoft\di\src\Container.php(153): Yiisoft\Di\Container->build()
#2 ****\vendor\yiisoft\yii-runner-http\src\HttpApplicationRunner.php(86): Yiisoft\Di\Container->get()
#3 ****\webroot\app\index.php(48): Yiisoft\Yii\Runner\Http\HttpApplicationRunner->run()

What is the expected result?

What do you get instead?

Additional info

Q	A
Version	1.0.?
PHP version
Operating system

Create console command for validate container configuration

This is may be useful for CI.

yii serve Error Code 127

i'm follow the readme.md and tried to test the yii3 and when i'm use "composer run server" show error

> yii serve
sh: yii: command not found
Script yii serve handling the serve event returned with error code 127

Suggest packages

Hi,
Thank you for the framework, first impression is good.

But could you add suggestion for necessary packages instead of error like: Class not found? Like it doing codeception when missing some packages.
Overall this mechanism should be maximum simple and controllable if someone will wont to add support for his own package.

Document boostrap.php

Need to document https://github.com/yiisoft/app/blob/master/src/ApplicationRunner.php#L64

RequestHandler

Question 1: How to resolve this one?

Uncaught Yiisoft\Factory\Exception\NotFoundException: No definition or class found for "Psr\Http\Server\RequestHandlerInterface". in /var/www/import/vendor/yiisoft/di/src/Container.php:390

Question 2: Why do we pointing on site alias in NotFoundHandler.php?

app/src/Handler/NotFoundHandler.php

Line 28 in 12a104f

$this->viewRenderer = $viewRenderer->withControllerName('site');

Use Twig

We should try to implement Twig templates in the app.

Main benefit is that it provides output escaping out of the box so there will be way less Yii 3 apps with XSS. Another thing is that it's a good idea to try using Twig with widgets and classes we have.

Catching server errors on initializing while working in browser

What steps will reproduce the problem?

1. install from scratch yiisoft/app
2. make configuration for using directly via browser (/etc/hosts + sites-available + a2ensite + systemctl reload apache2)
3. open web page in browser

What is the expected result?

working web page

What do you get instead?

nothing, just blank (white) page

Additional info

After addiing in index.php

ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');
error_reporting(E_ALL);

correct error occurs on web page:
PHP Fatal error: Declaration of Yiisoft\Log\Logger::log(mixed $level, Stringable|string $message, array $context = []): void must be compatible with Psr\Log\LoggerTrait::log($level, $message, array $context = [])

If init in console: /dev/app$ ./yii serve '127.0.0.1:8080', you can see the error directly in console. But if via browser, there is no clue that there is an error.

Q	A
Version	master
PHP version	8.0.16
Operating system	5.13.0-48-generic # 54~20.04.1-Ubuntu SMP Thu Jun 2 23:37:17 UTC 2022 x86_64
Build System	Linux
PHP Server API	FPM/FastCGI

route Group exception

Exception: Route should be either an instance of Route or Group, array given.

What steps will reproduce the problem?

change of the file app/config/routes.php:

declare(strict_types=1);

use App\Controller\SiteController;
use Yiisoft\Router\Route;
use \Yiisoft\Router\Group;

return [
    Route::get('/')->action([SiteController::class, 'index'])->name('home'),
    **Group::create('/api')
    ->middleware(ApiAuthentication::class)
    ->host('https://example.com')
    ->routes([
        Route::get('/comments'),
    ])**
];

What is the expected result?

What do you get instead?

Additional info

Q	A
Version	1.0.?
PHP version 8
Operating system

Improve starting page

Provide some useful links:

• Guide
• Readme
• Forum

Remove unnecessary parts

The following parts could be removed from the template (more to be added):

• Contact form.

Incorrect handling of CDN Css File

What steps will reproduce the problem?

composer create-project --prefer-dist --stability=dev yiisoft/app
composer run serve 

What is the expected result?

Fontawesome icons included

What do you get instead?

<link href="/https://use.fontawesome.com/releases/v5.13.0/css/all.css" rel="stylesheet">

Additional info

Q	A
Version	dev-master
PHP version
Operating system

Foxy\Exception\RuntimeException

When installing using composer, it's shows

- Installing foxy/foxy (v1.1.0): Loading from cache
Plugin installation failed, rolling back
- Removing foxy/foxy (v1.1.0)

[Foxy\Exception\RuntimeException]
No asset manager is found

Raise minimum PHP requirements

Since there's no sense to start new project with 7.4 when there's stable 8.0, raising minimum requirements for the application templates and demos (but not packages) could be done.

Asset manager ended with an error

Hi, when I installed Yii3. I got Asset manager ended with an error. The vendor folder doesn't even created.

| PHP version | 7.4
| Operating system | ubuntu 20.04

Display stacktrace on console error

See

app/src/Runner/ConsoleApplicationRunner.php

Line 58 in 17bdb74

$application->renderThrowable($error, new ConsoleBufferedOutput());

Move common config params from pakages to app

The idea is to move some common package params to config/params.php. For example, db connection, aliases, console controllers list.

Remove need to rebuild config

For now, if I add new console command to app, I have to rebuild config, to apply changes.

Even on development environment!

This behavior is the least expected and VERY surprising.

I must run composer du every time I change config... Pain (

How it should be?

1. Config caching must be an option.

2. Config caching must be DISABLED by default in development environment.

3. Config with disabled caching must be loaded from disk, fresh every time the app starts.

4. User MUST have a choice to enable or disable config caching at any moment.

5. Option CAN be enabled by default for production environment.

Serving app from localhost results in 404

What steps will reproduce the problem?

Install the app via composer as documented in the readme or the guide.
composer run serve works.

What is the expected result?

When pointing the browser to localhost/app/public/ I would expect the same result as running the app through the build in server.

What do you get instead?

I get a 404 page for the base path (localhost/app/public/)

Additional info

Q	A
Version	latest
PHP version	8.0.3 (MAMP Setup, .htaccess works on other projects)
Operating system	OS X

What's this?

What steps will reproduce the problem?
Where's the old community?
What is the expected result?
Why doesn't anyone come? Old fan leave out?
What do you get instead?
Like a private repo!

composer run serve EventDispatcher error

What steps will reproduce the problem?

I just ran composer create-project --prefer-dist --stability=dev yiisoft/app app
And then composer run serve

What is the expected result?

Start development webserver

What do you get instead?

PHP Fatal error: Uncaught Yiisoft\Factory\Exceptions\NotFoundException: No definition for Psr\EventDispatcher\EventDispatcherInterface in <removed>/vendor/yiisoft/di/src/Container.php:222

Additional info

Unsure what about my system setup is wrong here, couldnt find anything regarding this on google or obvious packages I needed to install. What am I missing?

Q	A
Version	1.0.?
PHP version	7.4.11
Operating system	Ubuntu 20.04

Suggestion: module-based folder structure?

I'm looking at the docs on directory structure and I notice that you seem to be going for a structure that's largely based on the type of the content that will go into the folders. For example resources/layout and resources/view and src/Controller and src/Command.

This is nothing new of course. In fact, most frameworks seem to do this. I've been seeing folder structures like this for 20 years now. Also often seen are public/scripts, public/images etc.

So familiar stuff... But best? I'd say no. Not even close.

If I build a new module for some app, say one that deals with uploads, and for that module I need some public assets (icons etc). some controllers, a command etc etc, I end up having to add folders all over the project. Wouldn't it be much nicer if we could have a folder structure based on modules? Where I place all the files related to a module in subfolders of a src/modules folder? To get a feel for what I mean have a look at this Stack Overflow question that asks about changing from one type of structure to the other and has some nice illustrative screenshots.

Have you guys given this any thought? I've always felt that the structure based on types is very inconvenient and I've also seen that people are never consistent about it. If you check what's inside public/images for example, sometimes they will have say 'icons' and 'backgrounds' folders in it (consistent), but mostly either directly under images or otherwise under images/icons and images/backgrounds people will almost always switch to a module-based structure. They end up with something like this:

• public
  • images
    • users
    • uploads
    • forum
  • scripts
    • users
    • uploads
    • forum

Now if they would be consistent, they would have

• public
  • images
    • icons
      • gif
      • png
    • backgrounds
      • jpg
      • png

...etc, continuing to split up based on the type of content. But people hardly ever do this. I almost always see the switch to module based approach. I reckon they do that because it just becomes ever more unwieldy as you keep doing this. Your code for one module will en up spread out over many different folders.

So why do so many frameworks give us a type-based structure out of the box?

I dare say it's out of convenience for the framework devs and because that's just how it's done in many other frameworks. I understand it's easier to serve all static files from public, expect all controllers under src/Controller etc. But again, best for the application / library developer? I say no.

So my question is have you given this much thought and would you consider going a different route here?

Debug panel not visible

What steps will reproduce the problem?

Clean install with composer create-project --prefer-dist --stability=dev yiisoft/app <app_name>
and composer run serve
Debugger is enabled in params file

    'yiisoft/yii-debug' => [
        'enabled' => true
    ],

What is the expected result?

Access the index page with debugger enabled

What do you get instead?

No debug panel is visible

Additional info

Q	A
Version	1.0.x-dev
PHP version	7.4.5
Operating system	Windows 10 x64

Move all generated files from "tests" to "runtime"

There is no need to store any generated files directly in "tests" folder.

Both "_output" and "_support/generated" folders with all content should be placed in "runtime/tests" folder.

There should be as minimum files as possible in "tests", to simplify understanding and usage.

Find a way not to pass CSRF token around

• https://github.com/yiisoft/app/blob/master/src/Controller/SiteController.php#L18 - explicitly passing CSRF token from request to view.
• https://github.com/yiisoft/app/blob/master/resources/layout/main.php#L29 - passing CSRF around.
• https://github.com/yiisoft/app/blob/master/resources/views/contact/form.php#L26 - explicitly using token.

That looks a bit too verbose and likely affects overall usability of the framework. Is there a way to avoid it?

Move providers out of the app where possible

• CacheProvider -> convert to closure, move to cache-file
• FieldProvider -> it is OK for it to stay where it is
• LoggerProvider, FileRotatorProvider, FileTargetProvider -> ???
• I18nProvider -> move to i18n converting to closure
• MailerInterfaceProvider, SwiftSmtpTransportProvider, SwiftTransportProvider -> move to mailer-swiftmailer converting to closure
• MiddlewareProvider - could be yii-web but questionable
• Psr17Provider -> move to config
• RouterProvider -> yii-web
• SessionProvider, FlashProvider -> yii-web
• WebViewProvider, ThemeProvider -> not possible, there's no Yii-specific package

CI build fails on master

All CI builds fail on master branch

Details: https://github.com/yiisoft/app/pull/138/checks?check_run_id=2066672971

Rename configs with defintions to `definitions-*`

common → definitions
web → definitions-web
console → definitions-console

This is will be more consistently with events, bootstrap, providers, routes and etc.

Now consider starting a new project on the yiisoft/app or yiisoft/yii-demo

Now I'm going to start a new project on yiisoft/app or yiisoft/demo. I don't know if it's suitable at present. I hope you can give me some suggestions

cache .env parsing result

See vlucas/phpdotenv#207 (comment)

Main motivation is performance.

Add prefix `@baseUrl` to the `@assetsUrl` alias

Try change https://github.com/yiisoft/app/blob/master/config/params.php#L22 to /projects/yii3basic/assets.

i think this value should be prefixed with @baseUrl: '@baseUrl/assets'

The @baseUrl alias will be changed automatically in the SubFolder middleware

Originally posted by @roxblnfk in https://github.com/yiisoft/app/issues/196#issuecomment-934737198

Add more features out of the box

• the "About" page,
• the "Contact" page, which displays a contact form that allows end-users to contact you via email,
• and the "Login" page, which displays a login form that can be used to authenticate end-users. Try logging in
  with "admin/admin", and you will find the "Login" main menu item will change to "Logout".

Set directory permissions on composer install

runtime and public/assets should be writeable.

Provide a way to set application environment

Now there is a note to not rebuild config in production but there is no method to set environment

install with composer seems freezed

launch sudo composer create-project --prefer-dist --stability=dev yiisoft/app testYii3

What is the expected result?

shows no signs of life, gets stuck on the message <Creating a "yiisoft / app" project at "./testYii3">

Additional info

Q	A
Version	1.0.?
PHP 7.4.3 (cli) (built: May 26 2020 12:24:22) ( NTS )
Ubuntu 20.04

Use config environments

We need to use config environments feature and have 2 default set of configs - dev (debug) and prod. Selecting one should be done through YII_ENV environmental variable (or .env).

Same should be applied to all templates and demo apps.

After new update ServerRequestInterface returning incorrect object

request model become work wrong

public function view(ServerRequestInterface $request): ResponseInterface {
        $response = $this->responseFactory->createResponse();

        $id = (int)$request->getAttribute('id');
        // Here error. Function return null, but before returned value.
        // Method GET.

Stop ignoring .lock

When we'll have most of the packages stable, package-lock.json and composer.lock should be removed from .gitignore and committed.

Group code by Use Case (Modules)

Instead of grouping project files by type, we should group them by "use cases" or "modules".

Old structure (typical for Yii2), grouping by type:

/src/Controllers/Module1/Module1Controller
/src/Controllers/Module2/Module2Controller
/src/Components/Module1/Component1
/src/Components/Module2/Component2
/views/module1/index
/views/module2/index
/tests/module1/Testcase
/tests/module2/Testcase

New refined modern structure with grouping by module:

/src/Module1/
             Controllers/Module1Controller
             Components/Component1
             Views/index
             Tests/Testcase
/src/Module2/
             Controllers/Module2Controller
             Components/Component2
             Views/index
             Tests/Testcase

1 module = 1 folder

Not only classes should be grouped by modules, but views and tests too.

Benefits:

1. Store in one place all that is used in one business feature. For example, code with tests that testing it. Easy to find, easy to manage.

2. Reuse module between projects with copy-paste module folder. Easy!

3. Fork modules to reuse in same project. Just copy that folder, and replace some logic.

4. Work in single folder at one time, tinkering some feature. No need to open 3-4 folders in project tree (code, tests, views, etc).

Re-do Codeception tests not to require a server

We can use functional tests only and remove any acceptance ones.

Not a bug, but it looks unsightly

public/index.php , line 14&15 use __dir__ , so vs code intelephense show the message.

Use a single layout template

Currently layout is broken into _footer.php, _head.php, _menu.php, main.php. Partials aren't reused so merging them into main.php will make things a little bit simpler.