create_directory()
public function create_directory(string $directory_path, int $permissions = 0755, bool $recursive = true): bool
Description
Creates a new directory at the specified path. This method allows for the creation of nested directories if they do not exist, subject to application security restrictions.
Understanding Paths: The create_directory() method works with paths relative to your application's root directory. There is no automatic "module" or "public" folder detection - you specify exactly where you want the directory created.
Parameters
| Parameter | Type | Description | Default | Required |
|---|---|---|---|---|
| $directory_path | string | The path where the directory should be created. | N/A | Yes |
| $permissions | int | Octal notation permissions (e.g., 0755). | 0755 | No |
| $recursive | bool | If true, creates all parent directories in the path. If false, fails if any parent directory doesn't exist. | true | No |
Return Value
| Type | Description |
|---|---|
| bool | Returns true if the directory was created successfully or already exists. |
Understanding the $recursive Parameter
The $recursive parameter controls whether the method will automatically create missing parent directories:
When $recursive is true (default):
If you try to create uploads/documents/2024 and neither uploads nor uploads/documents exist, the method will create all three directories automatically.
When $recursive is false:
If you try to create uploads/documents/2024 and uploads/documents doesn't exist, the method will fail and return false. All parent directories must already exist.
Why Use Non-Recursive Mode?
Setting $recursive to false is useful when:
- You want to ensure a specific directory structure already exists before proceeding
- You're validating that setup or installation steps were completed correctly
- You want to prevent accidental directory creation in unexpected locations
- You're implementing defensive checks in production code
How Paths Work
All paths are relative to your application's root directory (where your config, engine, and modules folders are located).
| If you specify... | It creates... | Best for... |
|---|---|---|
'uploads' |
/your-app/uploads/ |
General upload storage |
'public/uploads' |
/your-app/public/uploads/ |
Web-accessible files |
'modules/users/uploads' |
/your-app/modules/users/uploads/ |
Module-specific storage |
'/var/www/uploads' |
/var/www/uploads/ |
Absolute path storage |
Example #1
The code sample below demonstrates the most basic directory creation operation.
Safe to Call Multiple Times: The method returns true if the directory already exists, making it safe to call repeatedly without checking first. This "idempotent" behavior means you can call create_directory() before every upload operation without worrying about errors if the directory is already there.
Example #2
The example above shows how to create a directory with custom permissions.
Understanding Permissions: The default permission 0755 gives the owner (your PHP process) full control, while others can read and access the directory. Use 0700 for sensitive data (only owner can access), or 0775 when both owner and group need write access (common in shared hosting).
Example #3
The example above demonstrates creating nested directories automatically with recursive mode.
Example #4
The example above shows how to use non-recursive mode for validation.
When to Check First: While create_directory() is safe to call multiple times, you may want to check if a directory exists first when: (1) you need to perform different actions based on whether it's new or existing, (2) you're validating system setup, or (3) you want to provide specific user feedback. Use $this->file->exists($directory) to check before creating.
Example #5
The example above demonstrates organizing uploads into date-based directory structures.
Example #6
The example above shows how to set up a complete application directory structure.
Example #7
The example above demonstrates creating user-specific directories with proper permissions.
Example #8
The example above shows validation of required directory structure during application startup.
Non-Recursive Validation Pattern: When using $recursive = false for validation, the method returns false instead of throwing an exception if parent directories are missing. This makes it ideal for checking system requirements without disrupting application flow.
Example #9
The example above demonstrates creating temporary processing directories with unique names.
Example #10
The example above shows how to handle different permission requirements for different directory types.
Security Warning: Never use 0777 permissions on production servers. This gives everyone on the server full read/write/execute access to your directories, creating a major security risk. Stick to 0755 for general directories, 0700 for private data, and 0775 only when group write access is explicitly required.