Skip to content

Commit 6418be1

Browse files
serslonserslon
committed
Initial commit
0 parents  commit 6418be1

111 files changed

Lines changed: 16457 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.testing.example‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
ASTROLOGY_API_KEY=

‎.github/workflows/ci.yml‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
lint:
14+
name: Code Style
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Setup PHP
20+
uses: shivammathur/setup-php@v2
21+
with:
22+
php-version: '8.1'
23+
tools: composer:v2
24+
coverage: none
25+
26+
- name: Install dependencies
27+
run: composer install --no-interaction --prefer-dist
28+
29+
- name: Check code style
30+
run: PHP_CS_FIXER_IGNORE_ENV=1 composer lint
31+
32+
test:
33+
name: Tests (PHP ${{ matrix.php }})
34+
runs-on: ubuntu-latest
35+
strategy:
36+
fail-fast: false
37+
matrix:
38+
php: ['8.1', '8.2', '8.3', '8.4']
39+
steps:
40+
- uses: actions/checkout@v4
41+
42+
- name: Setup PHP
43+
uses: shivammathur/setup-php@v2
44+
with:
45+
php-version: ${{ matrix.php }}
46+
tools: composer:v2
47+
coverage: xdebug
48+
49+
- name: Install dependencies
50+
run: composer install --no-interaction --prefer-dist
51+
52+
- name: Run unit tests
53+
run: composer test:unit
54+
55+
- name: Run integration tests
56+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
57+
env:
58+
ASTROLOGY_API_KEY: ${{ secrets.ASTROLOGY_API_KEY }}
59+
run: composer test:integration
60+
61+
coverage:
62+
name: Coverage
63+
runs-on: ubuntu-latest
64+
needs: [lint, test]
65+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
66+
steps:
67+
- uses: actions/checkout@v4
68+
69+
- name: Setup PHP
70+
uses: shivammathur/setup-php@v2
71+
with:
72+
php-version: '8.3'
73+
tools: composer:v2
74+
coverage: xdebug
75+
76+
- name: Install dependencies
77+
run: composer install --no-interaction --prefer-dist
78+
79+
- name: Generate coverage
80+
run: vendor/bin/phpunit --testsuite Unit --coverage-clover coverage.xml
81+
82+
- name: Upload coverage to Codecov
83+
uses: codecov/codecov-action@v4
84+
with:
85+
file: coverage.xml
86+
token: ${{ secrets.CODECOV_TOKEN }}
87+
fail_ci_if_error: false

‎.github/workflows/release.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Release
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
publish:
12+
name: Notify Packagist
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Trigger Packagist update
16+
run: |
17+
curl -s -X POST \
18+
"https://packagist.org/api/update-package?username=${{ secrets.PACKAGIST_USERNAME }}&apiToken=${{ secrets.PACKAGIST_TOKEN }}" \
19+
-d '{"repository":{"url":"https://github.com/astro-api/astroapi-php"}}'
20+
21+
verify:
22+
name: Verify release
23+
runs-on: ubuntu-latest
24+
needs: publish
25+
steps:
26+
- uses: actions/checkout@v4
27+
28+
- name: Setup PHP
29+
uses: shivammathur/setup-php@v2
30+
with:
31+
php-version: '8.1'
32+
tools: composer:v2
33+
coverage: none
34+
35+
- name: Install dependencies
36+
run: composer install --no-interaction --prefer-dist
37+
38+
- name: Run unit tests
39+
run: composer test:unit
40+
41+
- name: Run integration tests
42+
env:
43+
ASTROLOGY_API_KEY: ${{ secrets.ASTROLOGY_API_KEY }}
44+
run: composer test:integration

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
/vendor/
2+
/.phpunit.result.cache
3+
/.phpunit.cache/
4+
/coverage/
5+
/docs/
6+
/.php-cs-fixer.cache
7+
/.idea/
8+
/.DS_Store
9+
/.env.testing
10+
coverage.xml
11+
./openapi.json

‎.php-cs-fixer.php‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<?php
2+
3+
$finder = PhpCsFixer\Finder::create()
4+
->in([__DIR__ . '/src', __DIR__ . '/tests'])
5+
->name('*.php');
6+
7+
return (new PhpCsFixer\Config())
8+
->setRiskyAllowed(true)
9+
->setRules([
10+
'@PSR12' => true,
11+
'array_syntax' => ['syntax' => 'short'],
12+
'declare_strict_types' => true,
13+
'phpdoc_align' => false,
14+
'phpdoc_to_comment' => false,
15+
'single_quote' => true,
16+
'strict_param' => true,
17+
])
18+
->setFinder($finder);

‎CLAUDE.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
PHP 8.1+ SDK client for the Astrology API v3. Package: `procoders/astrology-api-php`. Uses Guzzle 7 for HTTP transport. This is a standalone library (no framework, no database).
8+
9+
## Common Commands
10+
11+
```bash
12+
# Install dependencies
13+
composer install
14+
15+
# Run tests
16+
composer test # Full PHPUnit suite
17+
vendor/bin/phpunit tests/Unit/Categories/ChartsClientTest.php # Single test file
18+
vendor/bin/phpunit --filter testMethodName # Single test method
19+
20+
# Code coverage
21+
composer coverage # HTML report in coverage/ + text output
22+
23+
# Code style
24+
composer lint # Check only (dry-run)
25+
composer lint:fix # Auto-fix violations
26+
27+
# Documentation
28+
composer docs # Generate PHPDoc in docs/
29+
```
30+
31+
## Architecture
32+
33+
**Root Client:** `AstrologyClient` is the entry point. It creates a Guzzle client with middleware (retry, API key injection, logging) and exposes 26 readonly category client properties.
34+
35+
**Category Clients:** Each in `src/Categories/`, extending `BaseCategoryClient`. Methods validate inputs via `Validators` then delegate HTTP calls through `HttpHelper`. The `InsightsClient` is special — it contains 5 nested sub-clients (relationship, pet, wellness, financial, business).
36+
37+
**HTTP Layer:** `HttpHelper` interface with `GuzzleHttpHelper` implementation. Responses are normalized by extracting `data` or `result` fields from JSON.
38+
39+
**Validation:** All in `Utils/Validators.php` with static methods. Validation runs before every HTTP call. Throws `AstrologyError` on failure.
40+
41+
**Error Handling:** Single exception type `AstrologyError` with factory methods `fromGuzzleException()` and `normalize()`. Exposes `statusCode`, `errorCode`, `details` plus `isClientError()`/`isServerError()` helpers.
42+
43+
**Configuration:** `AstrologyClientConfig` (readonly) accepts array or object. Reads env vars: `ASTROLOGY_API_KEY`, `ASTROLOGY_API_BASE_URL`, `ASTROLOGY_DEBUG`. Retry config: `RetryConfig` (readonly).
44+
45+
## Code Conventions
46+
47+
- Every file uses `declare(strict_types=1)`
48+
- PSR-12 style enforced via PHP-CS-Fixer
49+
- Classes are `final` unless inheritance is needed
50+
- Heavy use of PHP 8.1+ `readonly` properties
51+
- PSR-4 autoloading: `Procoders\AstrologyApi\` → `src/`, `Procoders\AstrologyApi\Tests\` → `tests/`
52+
53+
## Testing Patterns
54+
55+
**Unit tests** (`tests/Unit/`): Use `SpyHttpHelper` and Guzzle's `MockHandler` — no real HTTP calls. Tests cover URL construction, validation, retry behavior, and error normalization. Always run.
56+
57+
**Integration tests** (`tests/Integration/`): Make real HTTP requests to the API. Automatically skipped when `ASTROLOGY_API_KEY` env var is not set. Each category has a test file with 1-3 representative endpoint calls.
58+
59+
```bash
60+
# Run only unit tests
61+
composer test:unit
62+
63+
# Run only integration tests (requires API key)
64+
ASTROLOGY_API_KEY=your_key composer test:integration
65+
66+
# Run both (integration tests skip without key)
67+
composer test
68+
```
69+
70+
PHPUnit 10 with random execution order and strict mode (fail on risky/warnings).
71+
72+
## Adding a New Endpoint
73+
74+
1. Add/update category client method in `src/Categories/` (extend `BaseCategoryClient`)
75+
2. Add validation logic to `Utils/Validators.php` if needed
76+
3. Call validation before the HTTP request in the method
77+
4. Write tests in `tests/Unit/Categories/` using `MockHandler`
78+
5. Run `composer lint:fix && composer test`

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Procoders
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)