marksitko / laravel-unsplash
Provides a fluent Unsplash API for Laravel
Installs: 88 600
Dependents: 1
Suggesters: 0
Security: 0
Stars: 81
Watchers: 2
Forks: 17
Open Issues: 5
Requires
- php: ^8.0
- guzzlehttp/guzzle: ^7.0
- illuminate/support: ^8.0|^9.0|^10.0|^11.0
Requires (Dev)
- orchestra/testbench: ^7.0|^8.0|^9.0
- phpunit/phpunit: ^9.0|^10.0
README
Provides a fluent api to use the Unsplash within Larvel applications. Use public actions or store images directly in your storage and persists all copyright informations automatically with the databse connector.
Install
$ composer require marksitko/laravel-unsplash
Laravel-Unsplash comes with package discovery and Laravel will register the service provider and facade automatically. Just in case you wanna add it manually, you should provide it in config/app.php
Service provider
'providers' => [ //... MarkSitko\LaravelUnsplash\UnsplashServiceProvider::class, ];
Facade
'aliases' => [ //... 'Unsplash' => MarkSitko\LaravelUnsplash\Facades\Unsplash::class, ];
Next you should publish the configuration.
$ php artisan vendor:publish --tag=config
Optional
If you wanna use Laravel-Unsplash with the database connector you have to publish the migration files.
$ php artisan vendor:publish --tag=migrations
It creates 2 migrations. One to store additional informations about stored image and one morph table to use it with the HasUnsplashables
trait.
Configuration
You have to provide a unsplash api access key in your .env
file.
Read how to generate a Unsplash API key
UNSPLASH_ACCESS_KEY=YOUR_GENERATED_API_KEY_FROM_UNSPLASH
Optional configurations:
# default is false
UNSPLASH_STORE_IN_DATABASE=BOOLEAN
# default is local
UNSPLASH_STORAGE_DISK=YOUR_STORAGE_DISC
Basic Usage
Take a look at the full Unsplash API documentation https://unsplash.com/documentation
Random Photos
// Returns the http response body. $twoRandomPhotosOfSomePeoples = Unsplash::randomPhoto() ->orientation('portrait') ->term('people') ->count(2) ->toJson(); // Store the image in on your provided disc $theNameFromTheStoredPhoto = Unsplash::randomPhoto() ->orientation('landscape') ->term('music') ->randomPhoto() ->store(); ];
Photos
$photos = Unsplash::photos()->toJson(); $photo = Unsplash::photo($id)->toJson(); $photosStatistics = Unsplash::photosStatistics($id)->toJson(); $trackPhotoDownload = Unsplash::trackPhotoDownload($id)->toJson();
Users
$user = Unsplash::user($username)->toJson(); $userPortfolio = Unsplash::userPortfolio($username)->toJson(); $userPhotos = Unsplash::userPhotos($username)->toJson(); $userLikes = Unsplash::userLikes($username)->toJson(); $userCollections = Unsplash::userCollections($username)->toJson(); $userStatistics = Unsplash::userStatistics($username)->toJson();
Search
$search = Unsplash::search() ->term('buildings') ->color('black_and_white') ->orientation('squarish') ->toJson(); $searchCollections = Unsplash::searchCollections() ->query('events') ->page($pageNumber) ->toJson(); $searchUsers = Unsplash::searchUsers() ->query('search_term') ->toJson();
Collections
$collectionsList = Unsplash::collectionsList() ->page($pageNumber) ->perPage($itemsPerPage) ->toJson(); $featuredCollection = Unsplash::featuredCollection() ->page($pageNumber) ->perPage($itemsPerPage) ->toJson(); $showCollection = Unsplash::showCollection() ->id($collectionId) ->toJson(); $showCollectionPhotos = Unsplash::showCollectionPhotos() ->id($collectionId) ->toJson(); $showCollectionRelatedCollections = Unsplash::showCollectionRelatedCollections() ->id($collectionId) ->toJson();
Topics
$topicsList = Unsplash::topicsList() ->page($pageNumber) ->perPage($itemsPerPage) ->toJson(); $showTopic = Unsplash::showTopic() ->id($topicIdOrSlug) ->toJson(); $showTopicPhotos = Unsplash::showTopicPhotos() ->id($topicIdOrSlug) ->toJson();
Stats
$totalStats = Unsplash::totalStats()->toJson(); $monthlyStats = Unsplash::monthlyStats()->toJson();
Usage with Database
If you wanna persist automaticly some informations (i.e. Copyrights) about you stored images you have to run the published migrations. In case you dont have ran the optional command, we start at the beginning:
$ php artisan vendor:publish --tag=migrations
$ php artisan migrate
When migration is successfull, you have to adjust the .env
UNSPLASH_STORE_IN_DATABASE=true
Now when you execute store()
on the Unsplash client, the image is stored in your provided disc and informations like
- the unsplash photo id
- the stored image name
- author name
- author link
However, these informations are all required to use a unsplash photo on your website.
Example with Unsplash Client
// Returns the created unsplash asset record $databaseRecord = Unsplash::randomPhoto()->store();
You are now also able to use the build in UnsplashAsset
Model
Example with UnsplashAsset Model
// Returns the created unsplash asset record $databaseRecord = UnsplashAsset::api()->randomPhoto()->store(); // Get an stored unsplash asset $unsplashAsset = UnsplashAsset::find($id);
You can also use the HasUnsplashables
Trait on any model.
Example with HasUnsplashables Trait on the User Model
use Illuminate\Foundation\Auth\User as Authenticatable; use MarkSitko\LaravelUnsplash\Traits\HasUnsplashables; class User extends Authenticatable { use HasUnsplashables; // ... }
Now you are able to use it like:
// store the unsplash asset in a morphToMany relation $unsplashAsset = Unsplash::randomPhoto()->store(); User::unsplash()->save($unsplashAsset); // retrive all related unsplash assets User::find($userId)->unsplash();
License
The MIT License (MIT). Please see License File for more information.
Laravel Package Boilerplate
This package was generated using the Laravel Package Boilerplate.