Standardize web app folder and file naming (Action.php vs. FolderNameHandler.php)

[ricksmort]

Proposed new feature or change

While learning my way around the Yii3 starter app, I found the naming of web entry points a bit confusing to follow. In the same project, we have two different styles for the same type of file:

HomePage: src/Web/HomePage/Action.php

NotFound: src/Web/NotFound/NotFoundHandler.php

As a new user, this made it difficult for me to tell what is a "framework requirement" and what is just a naming choice.
How this affects the learning curve:

"Is 'Action' a magic word?" When I see Action.php used repeatedly, my first thought is that the framework requires this specific name to work. It wasn't until I saw NotFoundHandler.php that I realized I could name these files whatever I wanted. Standardizing this would make it much clearer that these are just standard PHP classes.

Confusion in the Routing Logic The router uses ->action(Action::class). Seeing the word "action" used as a method, a class name, and a filename all at once made it hard for me to visualize the flow of data. Using a unique name like HomePageHandler makes it much easier to see the difference between the Router's command and my own code.

Difficulty Tracking Code While trying to understand how different pages connect, I found it hard to keep track of which file I was looking at. When my editor tabs all say Action.php, I have to keep checking the namespace just to remember which page's logic I'm editing.

The Suggestion: Follow the NotFoundHandler pattern

I think the NotFoundHandler approach is a much better "teaching tool" for the demo app. It shows exactly what the file is for and makes the routes.php file much easier to read without needing to alias every import.

Proposed Standard:

• Folder: src/Web/HomePage/
• Logic File: HomePageHandler.php (Descriptive and unique)
• View File: template.php

[samdark]

Thanks for feedback. Need to think about it.

[ricksmort]

After spending more time digging into the code, I wanted to share how I’ve started organizing my project. While the current "Action.php" setup works, I found it confusing and maybe others might too.

Instead of having one giant folder for everything, I prefer grouping my code by what it actually does.

├── assets/             # Source CSS/JS for Parcel to process 
├── config/             # Configuration & DI definitions 
│   ├── common/         # Shared DI/Params (DB, Sitemap Service) 
│   ├── web/            # Web routes and Middleware  
│   └── console/        # Console-specific commands 
├── public/             # Publicly accessible folder 
│   ├── index.php       # Entry script 
│   └── dist/           # Parcel's compiled React output 
├── resources/          # THE SEO BRIDGE 
│   └── views/          # Yii3 PHP views (Shells for React) 
│       ├── layout/     # Main Layout (React Root container) 
│       └── contact/    # Basic form fallback 
├── src/                # THE ENGINE (Feature-Based) 
│   ├── Contact/        # Emails, Support Logic 
│   ├── Shared/         # YOUR TOOLKIT (Middleware, Loggers, Sitemap) 
│   └── Infrastructure/ # Mailer setup, DB Factory, API Clients 
│   └── Console/        # Console-only Logic (e.g. daily stock sync) 
├── runtime/            # Logs, cache, temp files 
├── tests/              # Unit and Functional tests 
├── .env                # Secrets & local environment vars 
└── composer.json       # PSR-4: "App\\": "src/" 

Deeper look into "src/"

src/ 
├── Contact/                	# FEATURE: Support, Forms, Emails 
│   ├── Action(Controller)/     # ContactFormAction 
│   ├── Entity(Model)/       	# ContactEntity.php 
│   └── Service(Component)/     # MailerService (Your custom email logic) 
│ 
└── Shared/                   	# GLOBAL TOOLS: Your Yii2 Toolkit 
│   ├── Action(Controller)/     # HomeAction ErrorAction 
│   ├── Service(Component)/     # REPLACES: Helpers/Utils (RoleService, LogService) 
│   ├── Validator/           	# REPLACES: Custom Validators 
│   ├── Rbac/               	# NEW: RBAC definitions and rules 
│   ├── Middleware/         	# REPLACES: Controller Behaviors, UserProtectionMiddleware (Session security) 
│   └── Entity(Model)/        	# Common Entities (User, Account) 
├── Infrastructure/          	# Mailer setup, DB Factory, API Clients 
└── Console/                  	# REPLACES: Commands/Migrations logic 

Why I think this helps new users:

1. I stopped worrying about "Magic": When I see ContactAction.php, I know it's a file I named and control. When I just saw Action.php, I was afraid the framework might break if I renamed it.
2. It’s my "Map" from Yii2: Coming from Yii2, I was a bit lost at first. This structure gave me a mental bridge where I could clearly see that the Action(Controller) folder is where my Controllers go, Entity(Model) is for my Models, and Service(Component) is for my Components.
3. My routes are cleaner: In my routes.php file, the code is much easier for me to read. I can just write ->action(ContactAction::class) instead of having to import five different things called "Action."

[samdark]

1, 3. Naming the action is probably a good idea.
2. We wanted to change grouping by type to grouping by use case, so it was an intentional change compared to Yii2. See https://yiisoft.github.io/docs/cookbook/organizing-code/structuring-by-use-case-with-vertical-slices.html

[vjik]

While learning my way around the Yii3 starter app, I found the naming of web entry points a bit confusing to follow. In the same project, we have two different styles for the same type of file:

HomePage: src/Web/HomePage/Action.php

NotFound: src/Web/NotFound/NotFoundHandler.php

These are different type of files:

• NotFoundHandler implements RequestHandlerInterface and it can handle any request;
• Action is router action for concrete route.

Confusion in the Routing Logic The router uses ->action(Action::class). Seeing the word "action" used as a method, a class name, and a filename all at once made it hard for me to visualize the flow of data. Using a unique name like HomePageHandler makes it much easier to see the difference between the Router's command and my own code.

This is true. Create more specific name (ContactAction) is solution. But there is another way — namespace alias usage:

use App\UseCase;

Route::get('/diary/post/{slug}')->action(UseCase\Diary\Front\Post\Action::class)->name('diary/post/view'),
Route::get('/diary[/{page}]')->action(UseCase\Diary\Front\Listing\Action::class)->name('diary/post/index'),
Route::get('/users')->action(UseCase\Users\List\Action::class)->name('user/index'),
Route::methods(['GET', 'POST'], '/login')->action(UseCase\Login\Action::class)->name('login'),