Environments

Manage multiple deployment environments with hierarchical inheritance

What Are Environments?

Environments represent different deployment contexts for your API (local, staging, production). The package uses environment configurations to:

• Generate Postman and Insomnia environment files
• Inject correct server URLs into OpenAPI specifications
• Support variable inheritance through parent-child relationships
• Track resource IDs across CRUD operation chains

Base Environment

Defines shared variables inherited by all environments

Sub-Environments

Specific configs for artisan, local, production

Tracking Variables

Chain CRUD operations using resource IDs

Configuration

Environments are configured in config/openapi.php:

'environments' => [
    'base' => [
        'name' => 'Base Environment',
        'variables' => [
            'base_url' => env('APP_URL', 'http://localhost:8000'),
            'token' => '',
            'api_key' => '',
        ],

        // GLOBAL tracking variables for CRUD chaining
        'tracking_variables' => [
            'last_user_id' => '',
            'last_role_id' => '',
            'last_permission_id' => '',
        ],
    ],

    'artisan' => [
        'name' => 'Artisan Environment',
        'parent' => 'base',
        'variables' => [
            'base_url' => 'http://127.0.0.1:8000',
            'api_key' => '__GENERATED__',
        ],
    ],

    'local' => [
        'name' => 'Local Environment',
        'parent' => 'base',
        'variables' => [
            'base_url' => 'http://localhost/${{projectName}}/public',
            'api_key' => '',
        ],
    ],

    'production' => [
        'name' => 'Production Environment',
        'parent' => 'base',
        'variables' => [
            'base_url' => 'http://${{projectName}}.com',
            'api_key' => '',
        ],
    ],
],

Hierarchical Inheritance

Base Environment

The base environment is the parent for all other environments. It defines:

• Common variables - Shared across all environments
• Tracking variables - GLOBAL variables for CRUD chaining

The base environment is never used directly. It only provides defaults for sub-environments.

'base' => [
    'name' => 'Base Environment',
    'variables' => [
        'base_url' => env('APP_URL', 'http://localhost:8000'),
        'token' => '',
        'api_key' => '',
    ],
    'tracking_variables' => [
        'last_user_id' => '',
        'last_role_id' => '',
    ],
],

Sub-Environments

Sub-environments inherit from base and override specific variables:

Artisan

Used with php artisan serve:

'artisan' => [
    'name' => 'Artisan Environment',
    'parent' => 'base',  // Inherits from base
    'variables' => [
        'base_url' => 'http://127.0.0.1:8000',
        'api_key' => '__GENERATED__',
        // token is inherited from base
    ],
],

Final Variables:

{
  "base_url": "http://127.0.0.1:8000",
  "token": "",
  "api_key": "app_abc123...",
  "last_user_id": "",
  "last_role_id": ""
}

Local

Used for local development (XAMPP, Valet, etc):

'local' => [
    'name' => 'Local Environment',
    'parent' => 'base',
    'variables' => [
        'base_url' => 'http://localhost/${{projectName}}/public',
        'api_key' => '',
    ],
],

With Placeholder Replacement:

{
  "base_url": "http://localhost/my-app/public",
  "token": "",
  "api_key": "",
  "last_user_id": "",
  "last_role_id": ""
}

Production

Used for production deployment:

'production' => [
    'name' => 'Production Environment',
    'parent' => 'base',
    'variables' => [
        'base_url' => 'https://${{projectName}}.com',
        'api_key' => '',
    ],
],

With Placeholder Replacement:

{
  "base_url": "https://my-app.com",
  "token": "",
  "api_key": "",
  "last_user_id": "",
  "last_role_id": ""
}

Inheritance Logic

// From EnvironmentGenerator.php
protected function mergeVariables(array $config): array
{
    $variables = [];

    // If has parent, inherit variables
    if (isset($config['parent'])) {
        $parentConfig = config("openapi.environments.{$config['parent']}");

        if ($parentConfig) {
            // Inherit from parent
            $variables = array_merge(
                $parentConfig['variables'] ?? [],
                $parentConfig['tracking_variables'] ?? []
            );
        }
    }

    // Override with own variables
    $variables = array_merge($variables, $config['variables'] ?? []);

    return $variables;
}

Tracking Variables

Tracking variables are GLOBAL variables that enable chaining CRUD operations in Postman and Insomnia.

What Are Tracking Variables?

Tracking variables automatically capture resource IDs from create/update operations and use them in subsequent show/update/delete requests.

Example Flow:

1. POST /users (Create User)
   Response: {"data": {"id": 42, "name": "John"}}
   → Stores 42 in {{last_user_id}}

2. GET /users/{{last_user_id}} (Show User)
   Request: GET /users/42
   → Uses the stored ID automatically

3. DELETE /users/{{last_user_id}} (Delete User)
   Request: DELETE /users/42
   → Uses the same stored ID

Configuration

Tracking variables MUST be defined in the base environment only.

'base' => [
    'tracking_variables' => [
        'last_user_id' => '',
        'last_role_id' => '',
        'last_permission_id' => '',
        'last_product_id' => '',
        'last_order_id' => '',
    ],
],

Naming Convention

Format: last_{resource_name}_id

// For /users routes
'last_user_id' => '',

// For /products routes
'last_product_id' => '',

// For /api-apps routes
'last_api_app_id' => '',  // Use snake_case

How It Works

The generator automatically uses tracking variables for CRUD operations:

// From OpenApiServices.php
protected function getVariableName(string $paramName, string $uri, string $actionType): string
{
    $structure = $this->parseUriStructure($uri);
    $resourceName = $structure['entity'];

    $crudActions = ['show', 'update', 'destroy', 'edit'];
    $isCrudAction = in_array(strtolower($actionType), $crudActions);

    $trackingVars = config('openapi.environments.base.tracking_variables', []);
    $globalVarName = 'last_' . Str::snake($resourceName) . '_id';
    $hasTracking = array_key_exists($globalVarName, $trackingVars);

    $isIdParam = in_array($paramName, ['id', $resourceName . '_id']);

    // Use GLOBAL variable for CRUD actions with tracking
    if ($isCrudAction && $hasTracking && $isIdParam) {
        return $globalVarName;  // → last_user_id
    }

    // Use LOCAL variable for other actions
    return $paramName;  // → id
}

Generated Parameter References

With Tracking

For resources with tracking variables:

{
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "x-variable-name": "last_user_id",
      "schema": {"type": "integer"}
    }
  ]
}

In Postman/Insomnia:

GET /users/{{last_user_id}}
PUT /users/{{last_user_id}}
DELETE /users/{{last_user_id}}

Without Tracking

For resources without tracking variables:

{
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "x-variable-name": "id",
      "schema": {"type": "integer"}
    }
  ]
}

In Postman/Insomnia:

GET /webhooks/{{id}}
PUT /webhooks/{{id}}
DELETE /webhooks/{{id}}

Placeholder Support

Use ${{placeholderName}} syntax for dynamic values that are replaced during generation.

Available Placeholders

// From PlaceholderHelper.php
'${{projectName}}' → Project directory name (e.g., 'my-app')
'${{app_name}}' → APP_NAME from .env
'${{domain}}' → Derived from APP_URL

Usage Examples

Server URLs

'servers' => [
    [
        'url' => 'https://localhost/${{projectName}}/public',
        'description' => 'Local Server',
    ],
    [
        'url' => 'https://${{projectName}}.com',
        'description' => 'Production Server',
    ],
],

After Replacement:

{
  "servers": [
    {
      "url": "https://localhost/my-app/public",
      "description": "Local Server"
    },
    {
      "url": "https://my-app.com",
      "description": "Production Server"
    }
  ]
}

Environment Variables

'local' => [
    'variables' => [
        'base_url' => 'http://localhost/${{projectName}}/public',
        'api_key' => '${{app_name}}_local_key',
    ],
],

After Replacement:

{
  "base_url": "http://localhost/my-app/public",
  "api_key": "MyApp_local_key"
}

Generating Environment Files

Postman Environments

# Generate for specific environment
php artisan openapi:generate --format=postman --env=production

# Output includes separate environment JSON files
storage/app/public/openapi/
├── postman-collection.json
├── postman-env-artisan.json
├── postman-env-local.json
└── postman-env-production.json

Generated Postman Environment:

{
  "id": "postman-env-production",
  "name": "Production Environment",
  "values": [
    {
      "key": "base_url",
      "value": "https://my-app.com",
      "type": "default",
      "enabled": true
    },
    {
      "key": "token",
      "value": "",
      "type": "default",
      "enabled": true
    },
    {
      "key": "last_user_id",
      "value": "",
      "type": "default",
      "enabled": true
    }
  ],
  "_postman_variable_scope": "environment",
  "_postman_exported_at": "2024-03-07T10:30:00.000Z"
}

Insomnia Environments

php artisan openapi:generate --format=insomnia --env=local

# Output includes workspace with embedded environments
storage/app/public/openapi/
└── insomnia-workspace.json

Generated Insomnia Workspace:

{
  "_type": "export",
  "resources": [
    {
      "_id": "env_base_abc123",
      "_type": "environment",
      "name": "Base Environment",
      "data": {
        "base_url": "http://localhost:8000",
        "token": "",
        "last_user_id": ""
      }
    },
    {
      "_id": "env_local_def456",
      "_type": "environment",
      "parentId": "env_base_abc123",
      "name": "Local Environment",
      "data": {
        "base_url": "http://localhost/my-app/public"
      }
    }
  ]
}

Adding Custom Environments

1. Define Environment

   Add your environment to config/openapi.php:

   'environments' => [
       // ... existing environments
       
       'staging' => [
           'name' => 'Staging Environment',
           'parent' => 'base',
           'variables' => [
               'base_url' => 'https://staging.myapp.com',
               'api_key' => env('STAGING_API_KEY', ''),
           ],
       ],
   ],
   
2. Generate Documentation

   php artisan openapi:generate --env=staging
   

   The new environment will be included in generated Postman/Insomnia files.

3. Use in HTTP Endpoint

   curl "http://localhost:8000/documentation/openapi.json?env=staging"
   

Best Practices

Tracking Variables Location

• ALWAYS define tracking_variables in the base environment only
• NEVER define them in sub-environments
• They are automatically inherited by all sub-environments

Variable Naming

• Use descriptive names: base_url not just url
• Follow snake_case: api_key not apiKey
• Tracking variables: always use last_{resource}_id format

Sensitive Values

• Use empty strings for secrets: 'api_key' => ''
• Users fill in values after importing
• Use env() for development environments

Placeholder Usage

• Use for project-specific URLs
• Avoid for user-specific values
• Test placeholder replacement in generated files

Next Steps

Postman Collections

Learn how environments are used in Postman collections

Configuration Reference

Complete environment configuration options