How to Add a New Folder to Yii2 with Nginx

To add a new folder to a Yii2 application served by Nginx, you must create the directory within the web-accessible root (typically web/) and configure your Nginx server block to allow access to that location. This process involves updating the Nginx configuration file to include a specific location block or adjusting the existing try_files directive to prevent 404 errors when accessing resources in the new directory.

Understanding Yii2 Directory Structure

Yii2 follows a strict separation between runtime files and public web assets. The framework is designed so that only the web/ directory is publicly accessible from the internet. All other directories, such as config/, runtime/, and vendor/, are intentionally placed outside the document root for security reasons. When you need to add a new folder that users can access via a URL, it almost always needs to reside inside the web/ directory. If you place a folder directly in the project root (e.g., /var/www/html/myapp/newfolder), Nginx will reject requests due to permission restrictions defined in the server block. Therefore, the first step is determining whether the folder needs to be public-facing. For static assets, images, or downloadable files that should be accessible via http://example.com/newfolder/, the target path is web/newfolder.

Creating the New Folder

Once you have identified that the folder belongs in the public directory, you can create it using standard command-line tools. Navigate to your Yii2 project root and execute the following command:

mkdir -p web/newfolder

The -p flag ensures that parent directories are created if they do not exist, although in most standard Yii2 installations, the web/ directory already exists. You should also ensure that the web server user (usually www-data on Ubuntu/Debian or nginx on CentOS) has write permissions if the application needs to store files in this new folder dynamically. You can adjust permissions using:

chown -R www-data:www-data web/newfolder
chmod -R 755 web/newfolder

Without correct permissions, your application might throw a 500 Internal Server Error when trying to save data to this location, similar to issues described in Fixing 500 Server Error When Saving Pictures on Tech Support Site.

Configuring Nginx for Access

Nginx acts as a reverse proxy and static file server for Yii2. By default, many Yii2 Nginx configurations use a try_files directive that attempts to serve the file, then falls back to index.php for routing. If you simply create a folder, Nginx might still try to route the request through Yii2's router if the configuration is not explicit about handling directories. Open your Nginx server configuration file, typically located at /etc/nginx/sites-available/default or /etc/nginx/conf.d/yii.conf. Locate the server block. You have two primary options here. The first is to add a specific location block for your new folder. This is the cleanest approach if the folder contains static files like images or CSS that should bypass PHP processing entirely.

location /newfolder/ {
    alias /var/www/html/web/newfolder/;
    autoindex on;
}

Replace /var/www/html/ with your actual document root path. The alias directive maps the URL path to the filesystem path. The autoindex on directive is optional but helpful during development to list contents if no index file is present. After adding this block, test the configuration syntax with:

sudo nginx -t

If the test passes, reload Nginx to apply changes:

sudo systemctl reload nginx

If you prefer not to add a separate location block, you can rely on the default Yii2 Nginx template. Standard templates often include:

try_files $uri $uri/ /index.php?$args;

This line tells Nginx to check if the requested URI exists as a file ($uri), then as a directory ($uri/). If neither exists, it passes control to index.php. Since $uri/ checks for directories, creating the folder in web/ should automatically make it accessible without code changes, provided the folder is physically present and readable by the web server. However, if you encounter rewriting conflicts, such as those discussed in Troubleshooting Nginx Rewrite Overlapping with Swagger Body, an explicit location block is safer.

Verifying Accessibility

After configuring Nginx, verify that the folder is accessible by navigating to http://your-domain.com/newfolder/ in your browser. If you see a directory listing or a 403 Forbidden error, it means Nginx is recognizing the folder but lacks permission to list its contents. A 404 Not Found error indicates that the path mapping in Nginx is incorrect or the folder was not created in the web/ directory. Ensure that your Yii2 frontend controller does not have any middleware intercepting these URLs, which could result in unexpected behavior.

Frequently Asked Questions

Why do I get a 403 Forbidden error after creating the folder?

This usually happens because Nginx does not have permission to read the directory contents or list the files. Ensure that the ownership of the new folder matches the web server user, typically www-data, and that the permissions are set to at least 755.

Can I put the new folder outside the web directory?

No, folders outside the web/ directory are not publicly accessible by design in Yii2 for security reasons. If you need to store sensitive files there, you must provide a controlled download mechanism via a Yii2 controller action rather than direct URL access.

How do I handle dynamic file uploads in the new folder?

You need to ensure your Yii2 application has write permissions to the folder. Set the folder ownership to the web server user and verify that the PHP execution context has the necessary rights to create files within that directory structure.

What if my Nginx config uses try_files and the folder still returns 404?

Check that the physical path in your Nginx configuration matches the actual filesystem path exactly. Also, ensure there is no trailing slash mismatch between the location block and the alias directive, as this is a common source of 404 errors in Nginx setups.

Does adding a folder affect Yii2 routing?

If you use a dedicated location block with alias, the request bypasses Yii2 routing entirely and is handled directly by Nginx. If you rely on the default try_files setup, Nginx will check for the directory before passing the request to Yii2, so normal Yii2 routes remain unaffected unless you explicitly define conflicting rules.