run MockAPI-PHP in a hosting environment?

[stoppeye]

Hi!

This project looks very interesting! But how can I run it in a subdirectory of hosted environment and not just as a local server?

What is needed to get the routing to work? Are special rewrite rules in an .htaccess file required?

Thanks in advance!

[ka215]

Great question!
Yes, you can run MockAPI-PHP in a subdirectory on a hosted environment (Apache, Nginx, etc.), and I've just added complete configuration support for this as latest v1.3.2.

Quick Answer

1. ✅ .htaccess.sample file now included - Apache configuration with clear instructions
2. ✅ Standard deployment method - Designed for subdirectory installation
3. ✅ Complete deployment guide - See DEPLOYMENT.md for detailed instructions
4. ✅ Both Apache and Nginx supported

---

Standard Deployment Method (Subdirectory Installation)

The recommended way to deploy MockAPI-PHP is to git clone into a subdirectory and place the .htaccess file in the parent directory.

Directory Structure

/var/www/html/                    # Document root
├── .htaccess                     # ← Place .htaccess.sample here (renamed)
├── index.html                    # Your existing site files
├── about.html
└── MockAPI-PHP/                  # ← Git cloned directory
    ├── index.php
    ├── .htaccess.sample          # Sample file (copy to parent)
    ├── .env
    ├── responses/
    └── ...

Quick Setup Steps

1. Clone the repository

   cd /var/www/html
   git clone https://github.com/ka215/MockAPI-PHP.git
   cd MockAPI-PHP
   composer install --no-dev

2. Configure environment

   cp .env.sample .env
   # Edit .env if needed

3. Set up .htaccess in the parent directory

   cp .htaccess.sample ../.htaccess

   The .htaccess file contains:

   <IfModule mod_rewrite.c>
       RewriteEngine On
       RewriteBase /
       
       # Exclude existing files and directories
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteCond %{REQUEST_FILENAME} !-d
       
       # Redirect MockAPI-PHP requests to index.php
       RewriteRule ^(.*)$ MockAPI-PHP/index.php [QSA,L]
   </IfModule>

   Important: If you clone to a different directory name (e.g., mock-api), update the RewriteRule:

   RewriteRule ^(.*)$ mock-api/index.php [QSA,L]

4. Ensure Apache modules are enabled

   sudo a2enmod rewrite
   sudo systemctl restart apache2

5. Test your endpoints

   curl https://example.com/api/users
   curl https://example.com/api/version

---

Why This Approach?

This design has several advantages:

1. Clean separation: Your main site files remain untouched
2. Easy updates: Just git pull in the MockAPI-PHP directory
3. Multiple instances: You can run multiple mock APIs in different subdirectories
4. Standard practice: Follows common subdirectory deployment patterns

---

URL Structure

With subdirectory installation, your API endpoints follow this pattern:

https://example.com/[BASE_PATH]/[endpoint]

Examples:

• https://example.com/api/users
• https://example.com/api/products

Important Notes:

• The directory name (e.g., MockAPI-PHP) is part of the URL path
• BASE_PATH (default: /api) is the API endpoint prefix configured in .env
• You can change BASE_PATH to customize the API prefix

---

For Nginx Users

If you're using Nginx instead of Apache, add this configuration:

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    # Main site
    location / {
        try_files $uri $uri/ =404;
    }

    # MockAPI-PHP subdirectory
    location / {
        try_files $uri $uri/ /MockAPI-PHP/index.php?$query_string;

        location ~ \.php$ {
            fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;
        }
    }
}

---

Complete Documentation

I've created a comprehensive Deployment Guide that covers:

• ✅ Subdirectory installation (recommended standard method)
• ✅ Document root installation (for dedicated API servers)
• ✅ Apache configuration with .htaccess.sample
• ✅ Nginx configuration examples
• ✅ Environment configuration
• ✅ Troubleshooting common issues
• ✅ Security recommendations
• ✅ Performance optimization tips

---

Troubleshooting

If you get 404 errors:

1. Check .htaccess location: Must be in the parent directory, not inside MockAPI-PHP
2. Verify directory name: The RewriteRule must match your actual directory name
3. Check mod_rewrite: Ensure it's enabled in Apache
4. Check AllowOverride: Must be set to All in Apache config

Quick diagnostic:

# Check if .htaccess is in the right place
ls -la /var/www/html/.htaccess

# Check if mod_rewrite is enabled
apache2ctl -M | grep rewrite

# Test the endpoint
curl -I https://example.com/api/version

---

Files Updated

This response includes:

1. .htaccess.sample - Apache rewrite rules with clear documentation
2. DEPLOYMENT.md - Complete deployment guide with subdirectory focus
3. Updated README.md - Link to deployment guide
4. Updated README_JP.md - Japanese version with deployment note
5. Updated .gitignore - Excludes user-specific .htaccess files

---

Alternative: Document Root Installation

If you want to install MockAPI-PHP as the main application at the document root (e.g., https://api.example.com/api/users), you can also do that. See the "Document Root Installation" section in DEPLOYMENT.md for details.

---

TL;DR:

• ✅ Yes, works perfectly in subdirectories!
• ✅ Clone to subdirectory, copy .htaccess.sample to parent directory
• ✅ Update directory name in .htaccess if different from "MockAPI-PHP"
• ✅ See DEPLOYMENT.md for complete instructions

Let me know if you have any questions about the setup!

[stoppeye]

That's great news + thank you very much for such a speedy and in-depth response! I'm really busy today, but I hope, I'll find time to try this by tomorrow. I'll let you know.
Thanks again!

[stoppeye]

Sorry, it took me quite a bit longer to do some more testing. But the good new is: the setup works nicely in a hosted environment! 😊

I initially had some misconceptions about how the whole system with files in the responses folder works, but I think I got it now.

A few points from my side:

1. The version request doesn't work with the hosted environment (e.g. https://example.com/mock-api/api/version); I adjusted the condition in line 147:
   if ($method === 'get' && str_ends_with($request_uri, $BASE_PATH.'/version') ) {
   Maybe you find a better way to handle this, but it works for me (I didn't test it with a local server though).

2. The logic with first, second, third request (and having to reset the request count) seems a bit non-intuitive. I struggled with this (even though it's exactly what you say in your documentation...) at the beginning and thought that I had some strange caching issues.
   I'd prefer it, if a request like GET /users/3 would return the file 3.json, if it exists. I know you can force this with a mock_response GET param.
   The reason I was looking for a mock API is, that I want to test a middleware we are using/developing for making API requests.
   So if I want to make realistic requests (like on the real API, i.e. without any extra parameters) that return a specific, repeatable response, the 1st, 2nd, 3rd etc. request mechanism is really inconvenient.
   I think it makes sense, if you just do GET /users, but not for a specific request, where a corresponding file exists.
   I know you can do all this with your own hooks (great mechanism!), but I like the simplicity of your approach with the responses/ folder. It would therefore be great, if it would extend to files as well (i.e. if it exists, it will be served).

3. I don't quite see the point of the API_KEY and CREDENTIAL environment variables, at least in your default setup, since the only difference in index.php seems to be that the log message is different. Of course you can write your own hook again and do whatever you want in there.
   Our middleware supports 3 authentication mechanism: a X-* HTTP header with an API key, basic authentication with username + password and OAuth2 Bearer tokens.
   So to test this realistically, I wrote my own hook. I added a new X_API_KEY and redefined the CREDENTIAL environment variables:

X_API_KEY=X-Postmark-Server-Token|e737c0d5-0cf4-4bd6
  --> sends the HTTP header "X-Postmark-Server-Token: e737c0d5-0cf4-4bd6"
CREDENTIAL={username}:{password}
  --> sends the header "Authorization: Basic " . base64_encode('{username}: {password}'])

I then handle this in my own authorization.php hook:

<?php
if ( !empty($_ENV['X_API_KEY']) && strpos($_ENV['X_API_KEY'], '|') ) {
	list($header, $key) = explode('|', $_ENV['X_API_KEY']);
	$headers = getallheaders();
	if ( empty($headers[$header]) || $headers[$header] != $key ) {
		logAuthFailure($request_id, "Invalid X-API Key");
		unauthorizedResponse($request_id);
	}
} elseif ( !empty($_ENV['CREDENTIAL']) && strpos($_ENV['CREDENTIAL'], ':') ) {
    $auth_header = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
	if ( empty($auth_header) || $auth_header != 'Basic ' . base64_encode(str_replace(':', ': ', $_ENV['CREDENTIAL'])) ) {
		logAuthFailure($request_id, "Invalid username and password");
		unauthorizedResponse($request_id);
	}
} elseif ( !authorizeRequest($request_id) ) {
	unauthorizedResponse($request_id);
}

Maybe there are some things in there that you might consider to integrate in your own code.

Anyway, thank you for a great product! I really like the simplicity + flexibility of your approach.

[ka215]

Thanks for the detailed feedback. We are aligning .htaccess.sample and DEPLOYMENT.md so that subdirectory deployments have clearer rewrite guidance, and we added a path-normalizer in index.php to keep /version reachable when MockAPI-PHP lives under another folder. We also prototyped deterministic response selection (e.g., serving responses/users/get/3.json for /users/3) and are updating the API_KEY/CREDENTIAL documentation so it reflects the actual implementation. Final regression tests are still pending on our side, but we wanted to share the current direction before opening a PR.