PHP cURL Basic Guide
APIs (or Application Program Interfaces) are a set of rules, protocols, and tools that define how application components should interact with each other. This extends to how the application should function should it receive external information. Is the app to store the info? Is extra info to be returned in the response to an external request? Such things are to be considered when creating or using APIs in your programs.
That being said, the ability to both use and create APIs is a mark of an experienced coder and is crucial to learn when taking in new languages while also learning the syntax, fundamentals, and convention. With PHP, this is no exception; although you can use JavaScript for instance to handle your request, it is a great learning experience to learn how to handle the transfer of data in PHP from form inputs to the external request itself.
To get started, PHP’s primary way to access an external site’s information or make API requests is through a cURL request. cURL (aka Client URL) is a command-line tool for making external requests with various protocols, including (funnily enough) HTTP and HTTPS which is what we will use to request our data.
For our project we will make a request to cool API called IGDB, which is a video-game-centric site that provides access to video game data including characters, descriptions, art, and so much more. You will need to acquire a security key from the site, so be sure to create an account and follow the steps to get a key.
Next, we’ll first need to find how the site wants us to communicate for information. In IGDB’s docs, they list the endpoint required and the parameters for acquiring info from the site. For the application I’m making, I want to be able to search character data to find stuff about my favorite video game characters, so the endpoint I will focus on will be is “https://api-v3.igdb.com/characters”. With that in mind, let us get to the code.
Here is all the code required to get data we want from the IGDB API for now. This is a lot of code, so let's go through it step-by-step.
In the beginning, I’ve defined the API key I acquired from the database site. You never want to have your API plainly visible in your code or accessible from your site either. As such you’ll want to keep it in a safe place outside of the file that you’re serving in your folder. A good place is just outside the folder containing all of your PHP files. Just after, I’ve listed the IGDB wants me to query for characters. Onto the next step!
Here, I’ve made a search variable containing the name of everyone’s favorite plumber, Mario! Next, we call curl_init which creates a cURL session context and passes in the URL. This tells the instance who we’re connecting to for data. curl_init returns the context of the session, which we’re gonna need to complete our task, so I’ve saved the result of the init to variable $ch.
In order to tell the session what we want, we have to pass a few options into the session. This is done with the curl_setopt function. curl_setopt takes the session context (in this case being $ch), the name of the option that you wish to change or edit in the session, and the value to give that option. There is a large list of options, which is gone over in the PHP docs for cURL and I’d highly suggest glancing over them at the least to see what other options you might want to include in future projects.
In this case, we’re gonna use the curl_setopt_array function as it allows us to pass all of our options simultaneously into the request within an array. I’ve listed the request type as a “POST” request since we will be sending data and set two options, those being POSTFIELDS and HTTPHEADER. HTTPHEADER is where you give your headers. Headers are to be passed in the format shown above — an array with key-value pairs separated by a colon. As you can see I’ve passed my API key as “user-key” and an “Accept” parameter. That tells what type the data will be sent back as, in this case being JSON.
POSTFIELDS are another way to send options to the API. In this case, I’m telling the API to search for my $data variable’s value, Mario, give me back his name, gender, description, and species, and to limit the number of results to one. There’s only one Mario.
In order to finally send our request, we must call curl_exec on our session instance. This sends our request to the API and brings back the data and returns it. I save the returned data as res. In addition, I’ve set a$err variable as the call of curl_error on our context once more to catch any errors that come back from the server call. If there’s a mistake in my syntax or something is up with the API, the function should catch it and return it so I can see it and fix my mistakes.
Once that’s done, we can see our search results by echoing them to the page!
Here we either see our failure in the print or we see the results of our search. And with my current search of “Mario”, here’s what I’ve gotten back!
And that’s the basics of cURL requests in PHP. There are many other options that can be manipulated or passed and different APIs will mandate different ways in requesting data, so it’s all about reading the docs, testing, and asking questions. Downloading and using Postman is a huge help in understanding what formats your searches should be in and what it looks like in other languages as well.
