From b1de8788778a3e4ea428f14cd68e1684ffd7ca9e Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Wed, 9 Jul 2025 10:46:24 -0400 Subject: [PATCH 1/3] docs: Add comprehensive installation guide with system requirements, methods, and post-installation setup. --- docs/installation.md | 276 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 docs/installation.md diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..be0ec37 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,276 @@ +# Installation guide + +## System requirements + +- [`PHP`](https://www.php.net/downloads) 8.1 or higher. +- [`Composer`](https://getcomposer.org/download/) for dependency management. +- [`Yii2`](https://github.com/yiisoft/yii2) 2.0.53+ or 22.x. +- Web server (Apache, Nginx, or built-in PHP server). + +### Optional requirements + +- **Node.js**: For advanced asset compilation (optional) +- **Docker**: For containerized development + +## Installation methods + +### Method 1: Using Composer (Recommended) + +Create a new project using the Yii App Basic template. + +```bash +composer create-project --prefer-dist --stability=dev yii2-extensions/app-basic myapp +cd myapp +``` + +### Method 2: Manual installation + +1. **Download the template**: +```bash +git clone https://github.com/yii2-extensions/app-basic.git myapp +cd myapp +``` + +2. **Install dependencies** +```bash +composer install +``` + +### Method 3: Using Git + +Clone the repository and set up your project. + +```bash +git clone https://github.com/yii2-extensions/app-basic.git myapp +cd myapp +rm -rf .git +git init +composer install +``` + +## Post-installation setup + +### Directory permissions + +Ensure the following directories are writable by the web server. + +```bash +chmod 755 public/assets +chmod 755 runtime +chmod 755 tests/_output +``` + +### Environment configuration + +1. **Create environment file** (optional) +```bash +cp .env.example .env +``` + +2. **Configure database connection** in `config/web/components.php` +```php + [ + 'class' => 'yii\db\Connection', + 'dsn' => 'mysql:host=localhost;dbname=myapp', + 'username' => 'root', + 'password' => '', + 'charset' => 'utf8', + ], +]; +``` + +### Web server configuration + +#### Apache + +Create `.htaccess` in the project root. + +```apache +RewriteEngine on +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +RewriteRule ^(.*)$ public/$1 [L] +``` + +Create `public/.htaccess`. + +```apache +RewriteEngine on +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +RewriteRule . index.php +``` + +#### Nginx + +Add to your Nginx configuration. + +```nginx +server { + listen 80; + server_name myapp.local; + root /path/to/myapp/public; + index index.php; + + location / { + try_files $uri $uri/ /index.php?$query_string; + } + + location ~ \.php$ { + fastcgi_pass unix:/var/run/php/php8.1-fpm.sock; + fastcgi_index index.php; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + include fastcgi_params; + } + + location ~ /\.(ht|svn|git) { + deny all; + } +} +``` + +#### Built-in PHP server + +For development purposes. + +```bash +# Method 1: Using PHP built-in server +php -S localhost:8080 -t public + +# Method 2: Using Yii console command +./yii serve + +# Method 3: Custom host and port +./yii serve --host=0.0.0.0 --port=8080 +``` + +## Development setup + +### Database setup + +1. **Create database** +```sql +CREATE DATABASE myapp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +``` + +2. **Run migrations** (if available) +```bash +./yii migrate +``` + +3. **Seed test data** (optional) +```bash +./yii fixture/load +``` + +### Asset compilation + +For advanced asset management. + +```bash +# Install Node.js dependencies +npm install + +# Compile assets +npm run build + +# Watch for changes during development +npm run watch +``` + +## Docker setup + +### Using Docker Compose + +Create `docker-compose.yml`. + +```yaml +version: '3.8' + +services: + web: + image: yiisoftware/yii2-php:8.1-apache + ports: + - "8080:80" + volumes: + - .:/app + depends_on: + - db + environment: + - DB_HOST=db + - DB_NAME=myapp + - DB_USER=root + - DB_PASSWORD=secret + + db: + image: mysql:8.0 + environment: + - MYSQL_ROOT_PASSWORD=secret + - MYSQL_DATABASE=myapp + volumes: + - mysql_data:/var/lib/mysql + +volumes: + mysql_data: +``` + +Run the application. + +```bash +docker-compose up -d +``` + +### Using Docker directly + +```bash +# Build custom image +docker build -t myapp . + +# Run container +docker run -p 8080:80 myapp +``` + +### Performance optimization + +#### Enable OPcache + +Add to your `php.ini`. + +```ini +opcache.enable=1 +opcache.enable_cli=1 +opcache.memory_consumption=128 +opcache.interned_strings_buffer=8 +opcache.max_accelerated_files=4000 +opcache.revalidate_freq=60 +opcache.fast_shutdown=1 +``` + +#### Configure caching + +Enable cache components in `config/web/components.php`. + +```php +'cache' => [ + 'class' => 'yii\caching\FileCache', +], +'urlManager' => [ + 'enablePrettyUrl' => true, + 'showScriptName' => false, + 'enableStrictParsing' => false, + 'rules' => [ + // Your URL rules + ], +], +``` + +## Next steps + +Once the installation is complete. + +- ⚙️ [Configuration Reference](configuration.md) +- 💡 [Usage Examples](examples.md) +- 🧪 [Testing Guide](testing.md) From 593511a72cb89ef6b6702cfeed5f39d9cd21280a Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Wed, 9 Jul 2025 10:52:11 -0400 Subject: [PATCH 2/3] docs: Update Apache configuration instructions in installation guide to clarify `.htaccess` placement. --- docs/installation.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index be0ec37..f656b97 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -55,9 +55,7 @@ composer install Ensure the following directories are writable by the web server. ```bash -chmod 755 public/assets -chmod 755 runtime -chmod 755 tests/_output +chmod 775 public/assets runtime tests/_output ``` ### Environment configuration @@ -86,15 +84,6 @@ return [ #### Apache -Create `.htaccess` in the project root. - -```apache -RewriteEngine on -RewriteCond %{REQUEST_FILENAME} !-f -RewriteCond %{REQUEST_FILENAME} !-d -RewriteRule ^(.*)$ public/$1 [L] -``` - Create `public/.htaccess`. ```apache From 9fc4ae4291884fd8e79aad01ed63ef7d85b25f54 Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Wed, 9 Jul 2025 10:56:10 -0400 Subject: [PATCH 3/3] docs: Standardize capitalization in installation guide and README sections for consistency. --- README.md | 2 +- docs/installation.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6b0d728..9c26b5d 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ The Yii2 Web Application Basic template provides a complete foundation for build 3. **Security features** including CSRF protection and input validation. 4. **Development tools** for debugging, logging, and testing. -#### Why use this template? +#### Why use this template - **Rapid development**: Start building features immediately without setup overhead. - **Best practices**: Follow Yii2 conventions and modern web development standards. diff --git a/docs/installation.md b/docs/installation.md index f656b97..57481cb 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -14,7 +14,7 @@ ## Installation methods -### Method 1: Using Composer (Recommended) +### Method 1: Using composer (recommended) Create a new project using the Yii App Basic template. @@ -36,7 +36,7 @@ cd myapp composer install ``` -### Method 3: Using Git +### Method 3: Using git Clone the repository and set up your project. @@ -172,7 +172,7 @@ npm run watch ## Docker setup -### Using Docker Compose +### Using docker compose Create `docker-compose.yml`.