README

Socialize is a package that helps you to add social media features to your Laravel project easily.

You can share posts to Facebook, Twitter, Instagram and more is coming soon.

$fb = Socialize::facebook()
        ->setMessage('Awesome message')
        ->setLink('https://github.com/')
        ->setAction(OgAction::FEELS, OgObject::EXCITED)
        ->sharePost();

dump($fb->getPostId()); // 123456789101112

Or you can share posts using model trait.

$post = Post::first();
$response = $post->shareToFacebook();

echo $response->getPostId(); // 123456789101112

Table of Contents

• Installation
• Configuration
• Usage
  • Facebook
    • Initialization
    • Available Methods to set Options for sharePost() method
    • uploadPhoto(), deletePhoto(), uploadVideo(), deleteVideo()
    • getPosts()
    • getTaggedPosts()
    • getPost()
    • deletePost()
    • getComments()
    • getUrl()
  • Twitter
    • Initialization
    • tweet()
    • available methods to set options for a tweet
    • addComment()
    • uploadMedia(), getMediaIds()
    • addMedia()
    • deleteTweet()
  • Instagram
    • Initialization
    • publishImage()
    • publishImageCarousel()
    • addComment()
    • getUrl()
    • getPost()
  • Traits
    • Socializer
    • shareToFacebook(), shareToTwitter(), shareToInstagram()
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Installation

You can install the package via composer:

composer require draliragab/socialize

You can publish the config file with:

php artisan vendor:publish --tag="socialize-config"

This is the contents of the published config file:

return [
    'facebook' => [
        'default' => [
            'app_id' => env('FACEBOOK_APP_ID'),
            'graph_version' => env('FACEBOOK_GRAPH_VERSION', 'v15.0'),
            'page_id' => env('FACEBOOK_PAGE_ID'),
            'page_access_token' => env('FACEBOOK_PAGE_ACCESS_TOKEN'),
        ],
    ],

    'instagram' => [
        'default' => [
            'graph_version' => env('INSTAGRAM_GRAPH_VERSION', 'v15.0'),
            'user_access_token' => env('INSTAGRAM_USER_ACCESS_TOKEN'),
            'instagram_account_id' => env('INSTAGRAM_ACCOUNT_ID'),
        ],
    ],

    'twitter' => [
        'default' => [
            'app_consumer_key' => env('TWITTER_CONSUMER_KEY'),
            'app_consumer_secret' => env('TWITTER_CONSUMER_SECRET'),
            'account_access_token' => env('TWITTER_ACCOUNT_ACCESS_TOKEN'),
            'account_access_token_secret' => env('TWITTER_ACCOUNT_ACCESS_TOKEN_SECRET'),
        ],
    ],

    'model_columns' => [
        'message_column' => 'title',
        'photo_column' => 'image',
    ],
];

Configuration

For each social media you need to add the required credentials to your .env file or directly to the published config file.

By default, the package will use the default configuration. But you can publish to multiple pages and accounts by adding more configurations.

return [
    'facebook' => [
        'default' => [
            'app_id' => env('FACEBOOK_APP_ID'),
            'graph_version' => env('FACEBOOK_GRAPH_VERSION', 'v15.0'),
            'page_id' => env('FACEBOOK_PAGE_ID'),
            'page_access_token' => env('FACEBOOK_PAGE_ACCESS_TOKEN'),
        ],

        'page_2' => [
            'app_id' => env('FACEBOOK_APP_ID_2'),
            'graph_version' => env('FACEBOOK_GRAPH_VERSION', 'v15.0'),
            'page_id' => env('FACEBOOK_PAGE_ID_2'),
            'page_access_token' => env('FACEBOOK_PAGE_ACCESS_TOKEN_2'),
        ],
    ],
];

and pass the configuration name to the initialization method.

$fb = Socialize::facebook('page_2');

Usage

All the social media providers have share and getPostId methods.

$fb = Socialize::facebook()
        ->share(
            message: 'Awesome message',
            image: 'https:example.com/image.jpg',
            options: [],
        );

$postId = $fb->getPostId();

Facebook

Initialization

$fb = Socialize::facebook();

Accepts the configuration name as a parameter.

use DrAliRagab\Socialize\Socialize;

$fb = Socialize::facebook('page_2');

Available Methods to set Options for sharePost() method

setBackdatedTime(float|Carbon $backdated_time)
setBackdatedTimeGranularity(string $backdated_time_granularity) // One of ['year', 'month', 'day', 'hour', 'minute']
addChildAttachment(string $link, string $name = null, string $description = null, string $image_hash = null, string $picture = null)
setFeedTargeting(int $age_max = null, int $age_min = null, array $college_years = null, array $education_statuses = null, array $genders = null, array $geo_locations = null, array $interests = null, int $locales = null, array $relationship_statuses = null)
setLink(string $link)
setMessage(string $text)
setMultiShareEndCard(bool $multi_share_end_card = true)
setMultiShareOptimized(bool $multi_share_optimized = true)
setObjectAttachment(string $object_attachment)
setPlace(string $placeId)
setPublished(bool $published = true)
setScheduledPublishTime(int|Carbon $scheduled_publish_time)
setTags(array $tagsIds)
setTargeting(int $age_min = null, array $geo_locations = null)
setAction(OgAction $action, OgObject $object, ?OgIcon $icon = null)
attachMedia(int $mediaId)
attachMedias(array $mediaIds)

// After setting the options you can share the post
sharePost()

// Also after sharing you can add comments to the post
addComment('Awesome comment')

// And you ca delete the post
deletePost(int $postId) // returns true if the post is deleted successfully

Example:

use DrAliRagab\Socialize\Socialize;
use DrAliRagab\Socialize\Enums\OpenGraph\OgAction;
use DrAliRagab\Socialize\Enums\OpenGraph\OgObject;

$fb = Socialize::facebook();
$response = $fb
    ->setBackdatedTime(now()->subDays(2))
    ->setBackdatedTimeGranularity('day')
    ->addChildAttachment(
        link: 'https://example.com/1',
        name: "Awesome name",
        description: "Awesome description",
        picture: "https://example.com/image.jpg"
    )
    ->addChildAttachment(
        link: 'https://example.com/2',
        name: "Awesome name 2",
        description: "Awesome description 2",
        picture: "https://example.com/image2.jpg"
    )
    ->setFeedTargeting(
        age_max: 65,
        age_min: 18,
    )
    ->setLink('https://example.com')
    ->setMessage('Awesome message')
    ->setMultiShareEndCard(true)
    ->setMultiShareOptimized(true)
    ->setPublished(true)
    ->setTargeting(
        age_min: 18
    )
    ->setAction(OgAction::FEELS, OgObject::EXCITED)
    ->sharePost()   // Must be called after setting the options
    ->addComment('Awesome comment');    // Must be called after sharing the post

$postId = $response->getPostId();   // Get the post id

// Delete the post
$deleted = $fb->deletePost($postId);

uploadPhoto(), deletePhoto(), uploadVideo(), deleteVideo()

uploadPhoto(string $photoUrl, string $caption = null, bool $published = false, bool $temporary = true)

Upload a photo to a Page.

$fb = Socialize::facebook();
$mediaId = $fb->uploadPhoto('https://example.com/image.jpg')->getMediaId();

// You can use the media id to attach it to a post
$postId = Socialize::facebook()
    ->attachMedia($mediaId)
    ->setMessage('Awesome image')
    ->sharePost()
    ->getPostId();

Or you can publish photos directly to a Page.

$photoId = Socialize::facebook()
    ->uploadPhoto('https://example.com/image.jpg', 'Awesome image', true, false)
    ->getMediaId(); // returns the photo id

$deleted = Socialize::facebook()->deletePhoto($photoId); // returns true if the photo is deleted successfully

getPosts()

get the posts of a Facebook Page. Returns Collection.

$data = Socialize::facebook()-getPosts();

Accepts two parameters:

• $limit maximum number of posts to return. Default is 25. Maximum is 100.
• $fields fields to return. see https://developers.facebook.com/docs/graph-api/reference/page/feed#readfields

getTaggedPosts()

get all public posts in which the page has been tagged.

getPost()

get a specific post by its id. Returns Collection.

accepts two parameters:

• $postId the post id
• $fields fields to return. see https://developers.facebook.com/docs/graph-api/reference/pagepost#fields

deletePost()

Delete a post by its id. Returns true if the post is deleted successfully.

getComments()

get comments of a post. Returns Collection.

accepts three parameters:

• $postId the post id
• $limit maximum number of comments to return. Default is 25. Maximum is 100.
• $fields fields to return. see https://developers.facebook.com/docs/graph-api/reference/pagepost#fields

getUrl()

get the url of a post.

Twitter

Initialization

$twitter = Socialize::twitter();

Accepts the configuration name as a parameter.

use DrAliRagab\Socialize\Socialize;

$twitter = Socialize::twitter('account_2');

tweet()

Publish a tweet to a Twitter account.

$twitter = Socialize::twitter();
$postId = $twitter->tweet('Awesome tweet')->getPostId();

available methods to set options for a tweet

superFollowersOnly()
addPlace(string $placeId)
addPoll(array $pollOptions, int $pollDuration)
quoteTweet(string $tweetId)
restrictReply(string $restrictReply)    // "mentionedUsers" and "following" are the only options
inReplyTo(string $tweetId)
addMedia(array $mediaIds)
tagUsers(array $usernames)

Example:

$postId = $twitter
    ->superFollowersOnly()
    ->addPoll(
        pollOptions: ['Disappointed 😞', 'Predictable 😐', 'Excited 😃'],
        pollDuration: 60,
    )
    ->quoteTweet('12345679101112')
    ->restrictReply('mentionedUsers')
    ->inReplyTo('12345679101112')
    ->tweet(
        text: 'https://example.com/',
    )->getPostId();

addComment()

Add a comment to a tweet.

$postId = $twitter
    ->tweet('Awesome tweet')
    ->addComment('Awesome comment')
    ->getPostId();

uploadMedia(), getMediaIds()

Upload media to the account

accepts an array of media paths.

$imgPath = public_path('default-page-img.png');
$imgPath2 = public_path('default-page-img2.png');

$mediaIds = $twitter->uploadMedia([
    $imgPath,
    $imgPath2,
])->getMediaIds();

addMedia()

Add media to a tweet.

accepts an array of media ids.

$postId = $twitter
    ->addMedia($mediaIds)
    ->tweet('Awesome tweet')->getPostId();

You can combine uploadMedia() and addMedia().

$postId = $twitter
    ->uploadMedia([$imgPath])
    ->addMedia()
    ->tweet('Awesome tweet')
    ->getPostId();

deleteTweet()

Delete a tweet by its id. Returns true if the tweet is deleted successfully.

Instagram

Initialization

$insta = Socialize::instagram();

Accepts the configuration name as a parameter.

use DrAliRagab\Socialize\Socialize;

$insta = Socialize::instagram('account_2');

publishImage()

Publish an image to an Instagram account.

accepts three parameters:

• $imageUrl the image url
• $caption the caption of the image
• $options an array of options. see https://developers.facebook.com/docs/instagram-api/reference/ig-user/media#query-string-parameters

$insta = Socialize::instagram();
$postId = $insta->publishImage('https://example.com/image.jpg', 'Awesome image')->getPostId();

publishImageCarousel()

Publish an image carousel to an Instagram account.

accepts three parameters:

• $imageUrls an array of image urls
• $caption the caption of the image
• $options an array of options. see https://developers.facebook.com/docs/instagram-api/reference/ig-user/media#query-string-parameters

$postUrl = $insta
    ->publishImageCarousel([
        'https://example.com/image.jpg',
        'https://example.com/image2.jpg',
        'https://example.com/image3.jpg',
    ], 'Awesome image')
    ->addComment('Awesome image')
    ->getUrl();

addComment()

Add a comment to a post.

$postId = Socialize::instagram()
    ->publishImage('https://example.com/image.jpg', 'Awesome image')
    ->addComment('Awesome image', $postId)
    ->getPostId();

getUrl()

get the url of a post.

$postUrl = Socialize::instagram()
    ->publishImage('https://example.com/image.jpg', 'Awesome image')
    ->getUrl();

getPost()

get a specific post by its id. Returns Collection.

accepts two parameters:

• $postId the post id
• $fields fields to return. see https://developers.facebook.com/docs/instagram-api/reference/ig-media#fields

Traits

Socializer

This trait is used to share to social media directly from the model.

use DrAliRagab\Socialize\Traits\Socializer;

class Post extends Model
{
    use Socializer;
}

shareToFacebook(), shareToTwitter(), shareToInstagram()

Share to social media directly from the model.

$post = Post::find(1);

$post->shareToFacebook();   // share to facebook
$post->shareToTwitter();    // share to twitter
$post->shareToInstagram();  // share to instagram

All of the above methods search for the image in the image column of the model and the message in the title column.

You can change the columns in the config file.

'model_columns' => [
    'message_column' => 'title',
    'photo_column' => 'image',
],

Or you can pass the message, image and sharing options as array.

$post->shareToInstagram([
    'photo' => 'https://example.com/image.jpg',
    'message' => 'Awesome post',
    'options' => [
        'scheduled_publish_time' => now()->addDays(2)->timestamp,
    ],
]);

Also you can pass the social media account.

$post->shareToTwitter([
    'photo' => public_path('default-page-img.png'),
    'message' => 'Awesome post',
    'config' => 'account_2',
]);

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ali Ragab
• All Contributors

License

The MIT License (MIT). Please see License File for more information.