Download the PHP package tourze/gitee-api-bundle without Composer

GiteeApiBundle

中文

[] (https://packagist.org/packages/tourze/gitee-api-bundle) [] (https://packagist.org/packages/tourze/gitee-api-bundle) [] (https://packagist.org/packages/tourze/gitee-api-bundle) [] (https://codecov.io/gh/tourze/php-monorepo)

A comprehensive Gitee API integration bundle for Symfony applications, providing OAuth authentication, API client, repository synchronization, and data management features.

Table of Contents

• Features
• Installation
• Requirements
• Configuration
• Usage
  • OAuth Authentication
  • Multiple Tokens
  • API Calls
  • Console Commands
  • Customizing the OAuth Flow
• Advanced Usage
• Data Model
• Service Architecture
• Security
• Error Handling
• Testing
• Contributing
• License

Features

• 🔐 OAuth 2.0 Authentication - Full OAuth flow with multiple token support per user
• 🔌 Comprehensive API Client - Access user info, repositories, branches, issues, and pull requests
• 🔄 Repository Synchronization - Sync and cache repository data locally
• 🎛️ Flexible Scope Management - Configure OAuth scopes per application
• 🏗️ Doctrine Integration - Entities for applications, tokens, and repositories
• 🛠️ Console Commands - CLI tools for data management
• 🎨 Customizable Controllers - Extend or replace default OAuth controllers
• 📦 Auto-configuration - Symfony Flex recipe for quick setup

Installation

1. Add the bundle to your project:

Requirements

• PHP 8.1 or higher
• Symfony 6.4 or higher
• Doctrine ORM 3.0 or higher

Configuration

1. Create and configure your Gitee OAuth application in the database:

By default, applications are configured with the following scopes:

• user_info: Access user information
• projects: Access repositories
• pull_requests: Access pull requests
• issues: Access issues
• notes: Access comments

Additional available scopes:

• enterprises: Access enterprise information
• gists: Access gists
• groups: Access groups
• hook: Access webhooks

2. Configure the callback URL in your Gitee application settings:

Usage

OAuth Authentication

The bundle provides built-in controllers for handling the OAuth flow. To start the authentication process, redirect users to:

The callbackUrl parameter supports the following template variables:

• {accessToken}: The OAuth access token
• {userId}: The user ID (Gitee username if no user is authenticated)
• {giteeUsername}: The Gitee username
• {applicationId}: The application ID

Example usage in your templates:

The bundle will:

1. Redirect users to Gitee's authorization page with configured scopes
2. Handle the OAuth callback
3. Store the access token
4. Redirect to the specified callback URL with template variables replaced, or to the homepage route if no callback URL is provided

Multiple Tokens

The bundle now supports multiple tokens per user per application. Each time a user authorizes the application, a new token is created instead of updating the existing one. When using the API, the most recently created valid token will be used.

API Calls

Console Commands

The bundle provides console commands to manage Gitee data:

gitee:sync:repositories

Synchronizes a user's Gitee repositories with the local database.

Arguments:

• userId: The user ID to sync repositories for
• applicationId: The ID of the Gitee application to use

Options:

• --force (-f): Force update all repository information even if no changes detected

The command will:

1. Fetch all repositories for the specified user using the application's OAuth token
2. Compare with existing local repository data
3. Create new repository records or update existing ones if changes are detected
4. Skip repositories that haven't been updated since the last sync (unless --force is used)
5. Display progress and summary statistics

Customizing the OAuth Flow

The default controllers provide a basic OAuth flow. You can customize the flow by:

1. Creating your own controller that extends the default one:

2. Or implementing the flow entirely in your own controller using the services:

Advanced Usage

Token Management

For applications requiring multiple authentication workflows or token management:

Custom API Endpoints

Extend the API client for custom endpoints:

Repository Filtering

Filter synchronized repositories based on criteria:

Data Model

The bundle provides three main entities:

GiteeApplication

Stores Gitee OAuth application configuration:

• Client ID and secret
• OAuth scopes
• Application metadata

GiteeAccessToken

Manages user OAuth tokens:

• Access and refresh tokens
• Token expiration
• User-application associations
• Support for multiple tokens per user

GiteeRepository

Caches repository information:

• Repository metadata
• Owner and permissions
• Clone URLs
• Last push timestamps

Service Architecture

The bundle provides several services:

• GiteeApiClient - HTTP client for Gitee API requests
• GiteeOAuthService - OAuth flow management
• GiteeRepositoryService - Repository data management
• Repository classes - Doctrine repositories for data access

Security

Token Security

• Store tokens securely in the database with proper encryption if needed
• Never expose access tokens in logs or error messages
• Implement token rotation for long-lived applications
• Use HTTPS for all OAuth redirects and API calls

Input Validation

• All entity properties include validation constraints
• API responses are validated before processing
• OAuth state parameters include CSRF protection

Scope Management

• Request only the minimum required scopes
• Validate scope requirements before API calls
• Allow users to review and revoke permissions

Rate Limiting

• Respect Gitee's API rate limits
• Implement exponential backoff for failed requests
• Monitor API usage patterns

Error Handling

The bundle throws GiteeApiException for API-related errors. Always wrap API calls in try-catch blocks:

Testing

Run the test suite:

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and ensure they pass
5. Submit a pull request

Please follow PSR-12 coding standards and write tests for new features.

License

This bundle is open-sourced software licensed under the MIT license.