holyhabit/oauth

Simple and secure OAuth integration for PHP projects

v0.1.0-alpha 2025-07-03 09:43 UTC

Requires

• php: ^8.1
• firebase/php-jwt: ^6.0
• league/oauth2-client: ^2.7
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.0 || ^2.0
• psr/log: ^1.0 || ^2.0 || ^3.0

Requires (Dev)

• aidan-casey/mock-client: ^2.0
• guzzlehttp/guzzle: ^7.0
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.0
• squizlabs/php_codesniffer: ^3.7

MIT

• Holy OAuth Contributors

README

Simple and secure OAuth integration for PHP projects with PKCE support and ID token validation.

Quick Start (10 lines)

composer require holyhabit/oauth:^0.1

use HolyOAuth\Core\OAuthManager;
use HolyOAuth\Providers\GoogleProvider;
use HolyOAuth\Storage\SessionStorage;

$storage = new SessionStorage();
$manager = new OAuthManager($storage);
$manager->registerProvider('google', GoogleProvider::create('client-id', 'secret', 'redirect-uri'));

// Login: header('Location: ' . $manager->getAuthorizationUrl('google'));
// Callback: $user = $manager->handleCallback('google', $_GET['code'], $_GET['state']);

Features

• 🔒 PKCE (S256) - Enhanced security with Proof Key for Code Exchange
• 🛡️ ID Token Validation - Verify JWT tokens from OAuth providers
• 🔑 CSRF Protection - 128-bit state tokens
• 📦 PSR Compliant - PSR-4, PSR-12, PSR-18
• 🚀 Easy Integration - Works with any PHP framework
• ✅ Well Tested - Unit tests with mock HTTP clients

Installation

composer require holyhabit/oauth:^0.1.0-alpha

Basic Example

See examples/basic for a complete working example.

<?php
require 'vendor/autoload.php';

use HolyOAuth\Core\OAuthManager;
use HolyOAuth\Providers\GoogleProvider;
use HolyOAuth\Storage\SessionStorage;
use HolyOAuth\Security\StateManager;

// Initialize
$storage = new SessionStorage();
$stateManager = new StateManager($storage);
$oauthManager = new OAuthManager($storage, $stateManager);

// Configure Google OAuth
$googleProvider = GoogleProvider::create(
    $_ENV['GOOGLE_CLIENT_ID'],
    $_ENV['GOOGLE_CLIENT_SECRET'], 
    'http://localhost:8000/callback.php'
);

$oauthManager->registerProvider('google', $googleProvider);

// Start OAuth flow
$authUrl = $oauthManager->getAuthorizationUrl('google');
header('Location: ' . $authUrl);

Documentation

• Installation Guide
• Integration Guide
• API Reference

Requirements

• PHP 8.1+
• ext-json
• ext-openssl

Security

• Uses PKCE (S256) by default for all OAuth flows
• Validates ID tokens using provider's JWK keys
• CSRF protection with cryptographically secure state tokens
• Supports HTTPS-only in production

License

MIT License. See LICENSE file.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Roadmap

• Google OAuth with PKCE
• Refresh token support
• Kakao OAuth provider
• Naver OAuth provider
• Database storage adapter
• Laravel integration package## Auto-update Test

Testing webhook auto-update: Thu Jul 3 18:58:00 KST 2025