There was an issue raised recently on my php2Bluesky library pointing out that the dimensions of images weren’t being passed and so they weren’t being displayed on Bluesky correctly. On investigation, I found this to be correct, but because of the way the code was currently implemented, I couldn’t fix it. The library needed to have control of the upload of images in order to get the dimensions and currently that wasn’t the case.
Breaking Changes Incoming
The history of php2Bluesky is that it started as a series of functions in a larger side project I was working on. I broke it out from there to create the initial library and so the structure reflected that.
I really dislike it when libraries that I use release a new version that breaks my code, but in this case, my choices were to either fix the image issue and break others’ code or leave the images not displaying correctly. I felt that I had to make the change, and if there was going to be pain involved, I might as well do something that I’d been considering for a while and move the code to Composer too.
Therefore, if you are currently using version one of php2Bluesky, I’m sorry, but your code will need updating before you can use version two.
Version two contains the following major changes:
- the package is now available from composer
- moved to a class based structure
- you no longer need to upload images to Bluesky, php2Bluesky handles that for you
- you can pass the parameters in rather than having to change the code.
Getting Started
The following describes how you can use the latest version of php2Bluesky starting with installing via Composer and then manually followed by some examples which should work with both installation types.
Installing via Composer
Composer is the easiest way to get started and it is quick and easy to get updates too. The steps to add to your project are as follows:
- install composer (if requied)
- add the BlueskyAPI
composer.phar require cjrasmussen/bluesky-api
- add php2Bluesky
composer.phar require williamsdb/php2bluesky
You are now ready to use the library and you can place the following at the top of your code:
require __DIR__ . '/vendor/autoload.php';
use williamsdb\php2bluesky\php2Bluesky;
$php2Bluesky = new php2Bluesky();
Installing Manually
If you are Composer agnostic then it is possible to load the library as an included file, although you will also need to load Clark Rasmussen‘s bluesky-api. The steps are as follows:
Download the latest version of functions.php from GitHub and place somewhere along with your code and add this to the top of your code:
include __DIR__ . '/functions.php';
use williamsdb\php2bluesky\php2Bluesky;
$php2Bluesky = new php2Bluesky();
Examples
Here are some examples to get you started.
Setup and connect to Bluesky
require __DIR__ . '/vendor/autoload.php';
use williamsdb\php2bluesky\php2Bluesky;
$php2Bluesky = new php2Bluesky();
$handle = 'yourhandle.bsky.social';
$password = 'abcd-efgh-ijkl-mnop';
// connect to Bluesky API
$connection = $php2Bluesky->bluesky_connect($handle, $password);
Simple text post with attached link card
// connect to Bluesky API
$connection = $php2Bluesky->bluesky_connect($handle, $password);
$text='This is a test post #development #test';
$link='https://php2bluesky.dev';
$response = $php2Bluesky->post_to_bluesky($connection,
$text=$text,
$media='',
$link=$link,
$alt='');
print_r($response);
if (!isset($response->error)){
$url = $php2Bluesky->permalink_from_response($response, $handle);
echo $url.PHP_EOL;
}
Uploading a post with a single image and embedded url
$filename1 = 'https://upload.wikimedia.org/wikipedia/en/6/67/Bluesky_User_Profile.png';
$text = 'Screenshot of Bluesky';
$alt = 'This is the screenshot that Wikipedia uses for their https://en.wikipedia.org/wiki/Bluesky entry.';
$response = $php2Bluesky->post_to_bluesky($connection, $text, $filename1, '', $alt);
print_r($response);
if (!isset($response->error)){
$url = $php2Bluesky->permalink_from_response($response, $handle);
echo $url.PHP_EOL;
}
Uploading a post with multiple images (both local and remote)
$filename1 = 'https://upload.wikimedia.org/wikipedia/en/6/67/Bluesky_User_Profile.png';
$filename2 = '/Users/neilthompson/Development/php2Bluesky/Screenshot1.png';
$filename3 = 'https://www.spokenlikeageek.com/wp-content/uploads/2024/11/2024-11-18-19-28-59.png';
$filename4 = '/Users/neilthompson/Development/php2Bluesky/Screenshot2.png';
$text = 'An example of four images taken both from a local machine and remote locations with some alt tags';
// send multiple images with text
$imageArray = array($filename1, $filename2, $filename3, $filename4);
$alt = array('this has an alt', 'so does this', 'and this', 'And this one too!');
$response = $php2Bluesky->post_to_bluesky($connection, $text, $imageArray, '', $alt);
print_r($response);
if (!isset($response->error)){
$url = $php2Bluesky->permalink_from_response($response, $handle);
echo $url.PHP_EOL;
}
Passing Parameters
Previously, if you wanted to change any of the parameters that php2Bluesky supported, you needed to edit the file and change them. Now, you can simply pass them when instantiating php2Bluesky. For example:
$php2Bluesky = new php2Bluesky($linkCardFallback = 'RANDOM',
$failOverMaxPostSize = FALSE,
$randomImageURL = 'https://picsum.photos/1024/536',
$fileUploadDir='/tmp');
The above shows all the options and their defaults so if they work for your project you don’t need to provide any of them. Alternatively, you can just provide the ones that you need, for example:
$php2Bluesky = new php2Bluesky($linkCardFallback = 'BLANK',
$fileUploadDir='./cache');
Upgrading from Version One
If you are upgrading from version one the biggest change, Composer aside, is that you no longer need to use the upload_media_to_bluesky function prior to calling post_to_bluesky. Instead of passing the result from upload_media_to_bluesky you now simply pass the image filename and the library will do the rest of the work.
This was changed because in order to work out the dimensions of the images, the library has to have access to the image itself rather than the response from Bluesky after the image has been uploaded, which is simply a pointer. I think that this makes the library easier as now you only have to connect and make one call to post.
As an example in version one if you wanted to upload four images you would need to do:
// send multiple images with text
$image1 = upload_media_to_bluesky($connection, $filename1);
$image2 = upload_media_to_bluesky($connection, $filename2);
$image3 = upload_media_to_bluesky($connection, $filename3);
$image4 = upload_media_to_bluesky($connection, $filename4);
$imageArray= array($image1, $image2, $image3, $image4);
$alt= array('this has an alt', 'so does this');
// send to Bluesky
$response = post_to_bluesky($connection, $text, $imageArray, '', $alt);
Now this is reduced to:
// send multiple images with text
$imageArray= array($filename1, $filename2, $filename3, $filename4);
$alt= array('this has an alt', 'so does this');
// send to Bluesky
$response = $php2Bluesky->post_to_bluesky($connection, $text, $imageArray, '', $alt);
I’m hoping that you’ll find it quick to simply remove the upload_media_to_bluesky calls and replace the filenames in the post_to_bluesky call.
Available Functions
Finally, there are now just four public functions:
bluesky_connect($handle, $password) – setup the connection to the Bluesky api, returns the connection string to pass to other functions.
post_to_bluesky($connection, $text, $media='', $link='', $alt='') – post to Bluesky. Connection and text are mandatory. Returns the response from Bluesky api.
permalink_from_response($response, $handle) – this takes the response from post_to_bluesky and your Bluesky handle and returns the permament url for the post.
The final function is a bit of an outlier as it isn’t about posting to Bluesky at all, instead it returns information about a given Bluesky post provided as an url.
get_from_bluesky($connection, $link) – get information about an individual Bluesky post. Given a connection string and a valid Bluesky post url it will return an object containing information about that post such as the text, any associated links, images and other facets.