-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
61 changed files
with
2,005 additions
and
191 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,179 +1,157 @@ | ||
| # BlueskySDK | ||
| <p align="center"> | ||
| <img src="art/logo-small.webp" alt="Logo" /> | ||
| </p> | ||
|
|
||
| # BlueSky SDK | ||
|
|
||
|  | ||
| [](https://opensource.org/licenses/MIT) | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
|
|
||
| ## Project Description | ||
|
|
||
| BlueskySDK is a PHP library used to interact with the Bluesky API. This library allows you to perform file uploads, create records, and other operations using the Bluesky API. | ||
| BlueSky SDK is a PHP library used for interacting with the [BlueSky API](https://docs.bsky.app/docs/get-started). This library allows you to perform various | ||
| operations using the BlueSky API. | ||
|
|
||
| ## Requirements | ||
|
|
||
| ```json | ||
| "require-dev": { | ||
| "phpunit/phpunit": "9.6.20", | ||
| "fakerphp/faker": "^1.23", | ||
| "phpstan/phpstan": "^1.12" | ||
| }, | ||
| "require": { | ||
| "ext-json": "*", | ||
| "ext-curl": "*", | ||
| "ext-fileinfo": "*", | ||
| "php": ">=7.4", | ||
| "nesbot/carbon": "2.x", | ||
| "shahmal1yev/gcollection": "^1.0" | ||
| }, | ||
| ``` | ||
| - **PHP**: 7.4 or newer | ||
| - **Composer**: [Dependency management tool](https://getcomposer.org/) for PHP | ||
|
|
||
| ## Installation | ||
|
|
||
| ```shell | ||
| To install BlueSky SDK via Composer, use the following command: | ||
|
|
||
| ```bash | ||
| composer require shahmal1yev/blueskysdk | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| After including the library in your project, you can refer to the following examples: | ||
| Once installed, you can start using the SDK to interact with the BlueSky API. Below are examples of how to | ||
| authenticate and perform various operations using the library. | ||
|
|
||
| ### Authentication and Basic Usage | ||
|
|
||
| ### Get Profile | ||
| First, instantiate the `Client` class and authenticate using your BlueSky credentials: | ||
|
|
||
| ```php | ||
| use Atproto\Clients\BlueskyClient; | ||
| use Atproto\API\App\Bsky\Actor\GetProfile; | ||
| use Atproto\Resources\App\Bsky\Actor\GetProfileResource; | ||
| use Atproto\Resources\Assets\LabelsAsset; | ||
| use Atproto\Resources\Assets\LabelAsset; | ||
| use Atproto\Resources\Assets\FollowersAsset; | ||
| use Atproto\Resources\Assets\FollowerAsset; | ||
| use Atproto\Client; | ||
| use Atproto\Resources\Com\Atproto\Server\CreateSessionResource; | ||
|
|
||
| $client = new BlueskyClient(new GetProfile()); | ||
| $client = new Client(); | ||
|
|
||
| $client->authenticate([ | ||
| 'identifier' => 'user@example.com', | ||
| 'password' => 'password' | ||
| ]); | ||
|
|
||
| /** @var GetProfileResource $user */ | ||
| $user = $client->send(); | ||
| // Authenticate using your identifier (e.g., email) and password | ||
| $client->authenticate($identifier, $password); | ||
|
|
||
| /** @var Carbon\Carbon $created */ | ||
| $created = $user->createdAt(); | ||
| // Once authenticated, you can retrieve the user's session resource | ||
| /** @var CreateSessionResource $session */ | ||
| $session = $client->authenticated(); | ||
| ``` | ||
|
|
||
| /** @var LabelsAsset<LabelAsset> $labels */ | ||
| $labels = $user->labels(); | ||
| ### Making Requests | ||
|
|
||
| /** @var FollowersAsset $knownFollowers */ | ||
| $knownFollowers = $user->viewer() | ||
| ->knownFollowers() | ||
| ->followers(); | ||
| BlueSky SDK provides a fluent interface to construct API requests. Use chained method calls to navigate through the | ||
| API lexicons and forge the request: | ||
|
|
||
| foreach($knownFollowers as $follower) { | ||
| /** @var FollowerAsset $follower */ | ||
|
|
||
| $name = $follower->displayName(); | ||
| $createdAt = $follower->createdAt()->format(DATE_ATOM); | ||
|
|
||
| echo "$name's account created at $createdAt"; | ||
| } | ||
| ```php | ||
| use Atproto\Contracts\ResourceContract; | ||
|
|
||
| // Example: Fetching a profile | ||
| $profile = $client->app() | ||
| ->bsky() | ||
| ->actor() | ||
| ->getProfile() | ||
| ->forge() | ||
| ->actor('some-actor-handle') // Specify the actor handle | ||
| ->send(); | ||
| ``` | ||
|
|
||
| ### File Upload | ||
| ### Handling Responses | ||
|
|
||
| BlueSky SDK supports both Resource and Castable interfaces, providing flexibility in handling API responses and | ||
| enabling smooth data manipulation and casting for a more streamlined development experience. | ||
|
|
||
| Responses are returned as resource instances that implement the `ResourceContract`. These resources provide methods | ||
| for accessing data returned by the API. | ||
|
|
||
| ```php | ||
| use Atproto\API\Com\Atrproto\Repo\UploadBlobRequest; | ||
| use Atproto\Clients\BlueskyClient; | ||
| use Atproto\Auth\Strategies\PasswordAuthentication; | ||
| // Retrieve properties from the profile | ||
| /** @var string $displayName */ | ||
| $displayName = $profile->displayName(); | ||
|
|
||
| /** @var Carbon\Carbon $createdAt */ | ||
| $createdAt = $profile->createdAt(); | ||
| ``` | ||
|
|
||
| $client = new BlueskyClient(new UploadBlobRequest); | ||
| ### Working with Assets and Relationships | ||
|
|
||
| $client->setStrategy(new PasswordAuthentication) | ||
| ->authenticate([ | ||
| 'identifier' => 'user@example.com', | ||
| 'password' => 'password' | ||
| ]); | ||
| BlueSky SDK allows you to access complex assets like followers and labels directly through the resource instances. | ||
|
|
||
| $client->getRequest() | ||
| ->setBlob('/var/www/blueskysdk/assets/file.png'); | ||
| ```php | ||
| use Atproto\Resources\Assets\FollowersAsset; | ||
| use Atproto\Resources\Assets\FollowerAsset; | ||
|
|
||
| $response = $client->execute(); | ||
| // Fetch the user's followers | ||
| /** @var FollowersAsset<FollowerAsset> $followers */ | ||
| $followers = $profile->viewer() | ||
| ->knownFollowers() | ||
| ->followers(); | ||
|
|
||
| echo "Blob uploaded successfully. CID: {$response->cid}"; | ||
| foreach ($followers as $follower) { | ||
| /** @var FollowerAsset $follower */ | ||
| echo $follower->displayName() . " - Created at: " . $follower->createdAt()->format(DATE_ATOM) . "\n"; | ||
| } | ||
| ``` | ||
|
|
||
| ### Record Creation | ||
| ### Example: Fetching Profile Information | ||
|
|
||
| Here is a more complete example of fetching and displaying profile information, including created dates and labels: | ||
|
|
||
| ```php | ||
| use Atproto\API\Com\Atrproto\Repo\CreateRecordRequest; | ||
| use Atproto\Clients\BlueskyClient; | ||
| use Atproto\Auth\Strategies\PasswordAuthentication; | ||
| use Atproto\API\App\Bsky\Actor\GetProfile; | ||
| use Atproto\Resources\App\Bsky\Actor\GetProfileResource; | ||
|
|
||
| $client = new BlueskyClient(new CreateRecordRequest); | ||
| $client = new BlueskyClient(new GetProfile()); | ||
|
|
||
| $client->setStrategy(new PasswordAuthentication) | ||
| ->authenticate([ | ||
| 'identifier' => 'user@example.com', | ||
| 'password' => 'password' | ||
| ]); | ||
|
|
||
| $record = new \Atproto\Builders\Bluesky\RecordBuilder(); | ||
| $client->authenticate([ | ||
| 'identifier' => 'user@example.com', | ||
| 'password' => 'password' | ||
| ]); | ||
|
|
||
| $record->addText("Hello World!") | ||
| ->addText("") | ||
| ->addText("I was sent via BlueskySDK: https://github.com/shahmal1yev/blueskysdk") | ||
| ->addCreatedAt(date_format(date_create_from_format("d/m/Y", "08/11/2020"), "c")) | ||
| ->addType(); | ||
| /** @var GetProfileResource $user */ | ||
| $user = $client->send(); | ||
|
|
||
| $client->getRequest() | ||
| ->setRecord($record); | ||
| // Output profile details | ||
| echo "Display Name: " . $user->displayName() . "\n"; | ||
| echo "Created At: " . $user->createdAt()->toDateTimeString() . "\n"; | ||
| echo "Labels: " . implode(', ', $user->labels()->pluck('name')->toArray()) . "\n"; | ||
|
|
||
| echo "Record created successfully. URI: {$response->uri}"; | ||
| ``` | ||
| ### Create Record (with blob) | ||
| // Accessing and iterating over followers | ||
| $followers = $user->viewer()->knownFollowers()->followers(); | ||
|
|
||
| ```php | ||
| use Atproto\API\Com\Atrproto\Repo\UploadBlobRequest; | ||
| use Atproto\Auth\Strategies\PasswordAuthentication; | ||
| use Atproto\Clients\BlueskyClient; | ||
| use Atproto\API\Com\Atrproto\Repo\CreateRecordRequest; | ||
|
|
||
| $client = new BlueskyClient(new UploadBlobRequest); | ||
|
|
||
| $client->setStrategy(new PasswordAuthentication) | ||
| ->authenticate([ | ||
| 'identifier' => 'user@example.com', | ||
| 'password' => 'password' | ||
| ]); | ||
|
|
||
| $client->getRequest() | ||
| ->setBlob('/var/www/blueskysdk/assets/file.png') | ||
| ->setHeaders([ | ||
| 'Content-Type' => $client->getRequest() | ||
| ->getBlob() | ||
| ->getMimeType() | ||
| ]); | ||
|
|
||
| $image = $client->execute(); | ||
|
|
||
| $client->setRequest(new CreateRecordRequest); | ||
|
|
||
| $record = (new \Atproto\Builders\Bluesky\RecordBuilder) | ||
| ->addText("Hello World!") | ||
| ->addText("") | ||
| ->addText("I was sent from 'test BlueskyClient execute method with both UploadBlob and CreateRecord'") | ||
| ->addText("") | ||
| ->addText("Here are the pictures: ") | ||
| ->addImage($image->blob, "Image 1: Alt text") | ||
| ->addImage($image->blob, "Image 2: Alt text") | ||
| ->addType() | ||
| ->addCreatedAt(); | ||
|
|
||
| $client->getRequest() | ||
| ->setRecord($record); | ||
|
|
||
| $response = $client->execute(); | ||
| foreach ($followers as $follower) { | ||
| echo $follower->displayName() . " followed on " . $follower->createdAt()->format(DATE_ATOM) . "\n"; | ||
| } | ||
| ``` | ||
|
|
||
| ### Extending the SDK | ||
|
|
||
| BlueSky SDK is built with extensibility in mind. You can add custom functionality by extending existing classes and | ||
| creating your own request and resource types. Follow the structure used in the SDK to maintain consistency. | ||
|
|
||
| ## Contribution | ||
| - If you find any bug or issue, please open an issue. | ||
| - If you want to contribute to the code, feel free to submit a pull request. | ||
|
|
||
| We welcome contributions from the community! If you find any bugs or would like to add new features, feel free to: | ||
|
|
||
| - **Open an issue**: Report bugs, request features, or suggest improvements. | ||
| - **Submit a pull request**: Contributions to the codebase are welcome. Please follow best practices and ensure that your code adheres to the existing architecture and coding standards. | ||
|
|
||
| ## License | ||
|
|
||
| This project is licensed under the MIT License. For more information, see the LICENSE file. | ||
| BlueSky SDK is licensed under the MIT License. See the LICENSE file for full details. |
File renamed without changes
Binary file not shown.
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.