I mentioned over the summer that I’d thrown together a quick PHP wrapper class for interacting with the Bluesky API / AT protocol. And by quick, I mean quick. I wrote it one night, did a blog post on it in the early morning the next day, and called it good.
Different issues with it came up over time and I made some tweaks but earlier this week an issue was posted that I had no workaround for, so it was time for some bigger changes to the library.
I had built session instantiation into the class constructor. Pass in the handle and password (or, more appropriately, an app password) and it would hit the com.atproto.server.createSession endpoint to create a new session for you. There was a problem, though, where if that failed, the class didn’t do anything with it. You could check to make sure that you actually got a DID after instantiating the class but I hadn’t really documented that and it felt like the wrong solution anyway.
So I added some code that threw an exception if com.atproto.server.createSession returned an error, with the idea that the exception could be caught and then you’d know a session wasn’t established.
But this didn’t really fix the issue. The root issue was my lack of understanding about com.atproto.server.createSession and com.atproto.server.refreshSession. And to be clear, I don’t know that I fully understand all of the session handling even still, but I think I at least have a better solution.
Colin Walker had forked BlueskyApi and added some refresh token caching but, while I wanted to provide the ability to do that caching, I didn’t want to bake it into the library, so I didn’t follow his example. Instead, I took the lead from my TwitterApi class and moved the session handling into an auth method.
The constructor now just sets the API path and you need to call the BlueskyApi::auth() method to actually get a session. If you pass in a handle and password, it will create a new session. If you pass in a refresh token, it will attempt to refresh your session.
As seen, if authorization doesn’t work, it throws an exception.
Then the BlueskyApi::getRefreshToken() method can be used to get the refresh token for any caching. It’s important to remember that the refresh token changes every time you create or refresh a session so if you use a cached refresh token, you have to re-cache the new refresh token.
As per usual, I wouldn’t say this is anything groundbreaking or particularly insightful. I do think it’s interesting, though, that there seem to be a bunch of people learning on the fly with regards to Bluesky and the AT protocol and it’s really fun to watch and take part in.
