Outdated documentation

[circmark]

I'm looking at the docs for the voice broadcasts (https://github.com/CallFire/CallFire-PHP-SDK/blob/1.1/docs/en/broadcasts/02.voice.md) and it looks out of date. Specifically, this line:

$request->setData(base64_encode(file_get_contents('hello_world.mp3')));

It doesn't work because there is no setData() method. It was removed in the last commit. Also, this line:

if(!($result instanceof Response\Resource) || !($soundMeta = $resource->getResource())) {

It won't work either because the $resource variable does not exist. Where is this supposed to come from?

Also, if you go to the api docs for the CreateSound class (http://callfire.github.io/CallFire-PHP-SDK/classes/CallFire.Api.Rest.Request.CreateSound.html) it still shows the getDate() method.

Do you have another example someplace that works? Should I not be using version 1.1.5?

[cpommiss]

Yeah, this SDK seems to be pretty broken as far as the examples are concerned. Best to just instantiate via the SOAP API and get operations done that way by referencing their SOAP API documentation.

A shame since this SDK seems well built but it also seems to be in flux and reverse engineering how it works is counterproductive.

[TheFrozenFire]

Hey @cpommiss,

Sorry if things seem a bit under-maintained in the SDK. Some other major projects at CallFire unfortunately took precedence for a while, but I'll be focusing again on keeping this SDK up-to-date going forward. Our engineering team is also working on a new API for the CallFire platform which will be much easier to understand and maintain tooling for. I'm personally excited for that. :)

I'll take a look at updating/clarifying the documentation for uploading sound files. It's admittedly a bit esoteric in the current version of the API.

Please feel free to open issues for anything you find that needs clarification. I'll see that it gets done.

[cpommiss]

Hey!

Thanks for the quick reply. I recently had to help someone out who was stuck with your API for a few days and he ended up being pretty late with the project. I was able to cobble together a solution via the SOAP API documentation, bypassing the SDK completely, which sucked, as I hate SOAP.

I ended up eventually moving over to the REST API because it seemed to be a lot faster than the SOAP API (probably due to all the XML overhead involved with SOAP).

It would be nice to someday migrate the app over to the PHP SDK. Hope you can get it up to speed soon! It may even be that the SDK works fine, but the documentation instructs the user to do the wrong things. You'd know better than me on that, though. :)

[TheFrozenFire]

If you find yourself in that situation again, please feel free to reach out to our customer support team. There are a few CSMs who have a pretty solid grasp on the API, and if there's something that they can't answer themselves, it'll usually get escalated to me directly. We're all too happy to help developers with their integrations. :)

I'd also suggest avoiding the SOAP API in the future, though not because of any issue with CallFire's implementation of it (the SOAP and REST implementations of CallFire's API are actually near-identical interfaces to the same internal API). Rather, because PHP's ext/soap is almost completely unmaintained, and has a few troublesome bugs that I encountered myself when developing this SDK, it can lead to some really weird behaviours (as well as some pretty big security holes).

The SDK should actually work very reliably. We had some issues a while back where our Swagger specification changed in a significant way (resulting in broken SDK generation), but I've since resolved those issues.

Please do let me know if you find holes in the SDK's documentation. I'm a pretty big stickler for good documentation (I actually help maintain PHP's own documentation as well), so I'll be heartbroken if my own docs are lacking. :)

CallFire is actively working on making its platform much more developer-friendly, so please don't hesitate to reach out if you have questions or concerns.

[gerardojbaez]

Still outdated.