Getting Started

Minimal Steps

Installation:
```
composer require adlawson/timezone:1.0.0
```
Add the autoloader to your entry point (e.g., index.php or bootstrap/app.php):
```
require __DIR__.'/vendor/autoload.php';
```
First Use Case:
- If your Laravel app triggers the DateTime timezone warning (e.g., during php artisan serve or API requests), this package silently enforces UTC as the default timezone, eliminating the warning.
- Test by running:
```
php artisan tinker
>>> new DateTime(); // No warning, defaults to UTC
```

Where to Look First

Source Code: lib/timezone.php (single file, ~50 lines).
Laravel Integration: No config needed—just autoload. For debugging, check if date_default_timezone_get() returns UTC after autoloading.

Implementation Patterns

Usage Patterns

Framework-Agnostic Initialization:
- Place require __DIR__.'/vendor/autoload.php'; before any DateTime usage in your Laravel app’s entry point (e.g., public/index.php or bootstrap/app.php).
- Example for Laravel’s bootstrap/app.php:
```
require __DIR__.'/../vendor/autoload.php'; // <-- Add this line early
$app = new Application();
```

Testing Timezone Behavior:

Use date_default_timezone_get() in tests to verify UTC is enforced:

use function PHPUnit\Framework\assertEquals;

public function testTimezoneIsUTC()
{
    assertEquals('UTC', date_default_timezone_get());
}

Avoiding Side Effects:
- Since the package violates PSR-1, do not use it in libraries/plugins. Reserve it for end-user applications (e.g., Laravel apps).

Workflows

Debugging Timezone Warnings:
- If warnings persist after autoloading, check:
  - php.ini for date.timezone overrides.
  - Server environment (e.g., shared hosting may restrict date_default_timezone_set()).
- Use error_reporting(E_ALL) to confirm the warning is suppressed.
Laravel-Specific Integration:
- Combine with Laravel’s config/app.php timezone setting (if present) by placing the autoloader before Laravel boots:
```
// bootstrap/app.php
require __DIR__.'/../vendor/autoload.php'; // Force UTC first
$app = new Application();
```

Fallback for Dynamic Environments:

Useful in CI/CD pipelines or Docker containers where php.ini isn’t configurable:

# docker-compose.yml
services:
  app:
    image: php:8.2-cli
    volumes:
      - ./vendor:/var/www/vendor
    command: php -d date.timezone=UTC script.php  # Redundant but explicit

Integration Tips

Composer Scripts: Add to composer.json to auto-enforce UTC during testing:

"scripts": {
  "test": "php -d date.timezone=UTC vendor/bin/phpunit",
  "pre-autoload-dump": "php -d date.timezone=UTC vendor/bin/composer dump-autoload"
}

Laravel Service Providers: If you must initialize after Laravel boots, use a service provider’s boot() method:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class TimezoneProvider extends ServiceProvider
{
    public function boot()
    {
        if (date_default_timezone_get() === false) {
            date_default_timezone_set('UTC');
        }
    }
}

(Note: This is redundant if the package is already loaded, but useful for explicit control.)

Gotchas and Tips

Pitfalls

PSR-1 Violation:
- The package executes code on autoload, which violates PSR-1 §2.3. This can cause:
  - Unexpected behavior in libraries that assume date.timezone is untouched.
  - Issues with static analysis tools (e.g., PHPStan) flagging side effects.
- Workaround: Only use in application code, not libraries.
Redundant Overrides:
- If date.timezone is already set in php.ini or via ini_set(), the package’s check may still run but won’t override. Test with:
```
php -d date.timezone=America/New_York -r "require 'vendor/autoload.php'; echo date_default_timezone_get();"
```
  (Should output UTC, not America/New_York.)
Laravel Caching:
- If using Laravel’s OPcache or config_cache, the autoloader may run once during boot. For dynamic environments, ensure the package is loaded before Laravel caches configurations.
Timezone Database Updates:
- The package uses PHP’s built-in timezone database. If your app relies on IANA timezone updates, ensure your PHP version is up-to-date (e.g., PHP 8.2+ includes newer IANA data).

Debugging

Verify Execution:
- Check if the package ran by inspecting date_default_timezone_get() in a Laravel Tinker session:
```
>>> date_default_timezone_get();
"UTC"
```
- If not UTC, the autoloader may not have executed (e.g., cached OPcode).
Suppress Warnings:
- If warnings persist, explicitly set the timezone in bootstrap/app.php after autoloading:
```
require __DIR__.'/../vendor/autoload.php';
date_default_timezone_set('UTC'); // Explicit fallback
```
Check for Conflicts:
- Other packages (e.g., vlucas/phpdotenv) might also set timezones. Use strace or xdebug to trace execution order:
```
strace -e trace=file php artisan tinker 2>&1 | grep timezone
```

Tips

Explicit Overrides:
- For production, set date.timezone in php.ini or .env (Laravel) to avoid relying on the package:
```
; php.ini
date.timezone = UTC
```
  or
```
# .env
APP_TIMEZONE=UTC
```

Testing Edge Cases:

Test with date.timezone unset in php.ini:

php -n -r "require 'vendor/autoload.php'; echo date_default_timezone_get();"

(Should output UTC.)

Alternative for Libraries:
- If you’re building a library and need timezone safety, require users to set date.timezone in their composer.json or documentation:
```
"config": {
  "preferred-install": "dist",
  "timezone": "UTC" // Hint for users
}
```

Performance Note:

The package adds negligible overhead (~1ms on autoload). For micro-optimizations, consider inlining its logic:

// bootstrap/app.php
if (function_exists('date_default_timezone_get') && !date_default_timezone_get()) {
    date_default_timezone_set('UTC');
}

Forking for Custom Logic:

Fork the package to add logging or custom timezone logic (e.g., detect user’s timezone via IP):

// Custom timezone.php
require '/path/to/adlawson/timezone/lib/timezone.php';
if (date_default_timezone_get() === 'UTC') {
    error_log('UTC enforced by timezone package');
}

Timezone Laravel Package