 Good morning, good afternoon, good evening, good day, wherever you may be in the world. I'm gonna just steal that from the Truman Show. I think it's a great way to start these things. Welcome everybody who is joining us today. Yesterday, I was with Adrian in another call and we were getting ready for an accessibility day session that I am volunteering for. And now, suddenly my views have all changed because we were fiddling with our Zoom views yesterday. But that's okay, nothing major is broken, but I just realized that certain things are not exactly as I'm used to them, but that's fine. I will work my way through. Welcome everybody joining today. As you are joining in the chat, please do let us know where you are joining us from and then perhaps share a little bit about who you are, where you're from, what you do with WordPress, what you don't do with WordPress. I don't mind whatever you feel like sharing in the chat as you join while I do my typical workshop introduction. So my name is Jonathan. I live in Cape Town in South Africa. It is now the 21st of September, which should mean that Cape Town starts getting warmer and I'm just not seeing any of that warm weather. And I know that folks in Europe that I talk to are talking about it being a bit of a heat wave that side of the world. I'm assuming it's similar-ish in the United States. So it seems the weather is doing weird things. I am still cold. That's why I'm wearing this warm sweater. So hopefully, however you are, you are warm at least, or at least have a warm drink if you need it. I am a developer educator at Automatic. I'm sponsored to work with the training team. The training team is a team within the WordPress project that creates all kinds of educational content around using WordPress, building with WordPress, developing for WordPress. And I'm one of those team members. And if you wanna find me online, you can find me at my blog, it's jonathanbossinger.com. Adrian says, sorry if we break your Zoom meetings. It's actually not that much of a big issue. I normally just have my video right at the top of my view and that's now gone because we were fiddling with that yesterday. So I'm gonna have to figure out how to get that back. But maybe that's not a bad thing because I tend to, when I'm presenting, I tend to speak to, I come from a, I'm not a traditional teacher or educator, but my instructional experience is from working with people in the real world. So I tend to focus on a face. And often in these workshops, most folks have disabled their videos of the face that I'm focusing on as myself. So Adrian, I appreciate the fact that your video is enabled. I'm gonna be focusing on you today, but feel free to disable it if you don't want to. Rico says, I'm from Switzerland and I work as a teacher for adults and my others WordPress, excellent. Rico and I share that similarity. We've got Mark from Isoqua. Rico says, you are a great teacher. Thank you, Rico. I appreciate that. I don't consider myself a great teacher. I just do the best that I can. There's always, I always believe there's always room to improve, but I thank you for your very kind words. Okay, today we are diving into the WordPress Options API. This week's session is actually part of a two-part series, if you will. Next week we're going to be diving into, sorry, my screen just went weird. Next week we're going to be diving into the Settings API and the Options API and the Settings API work together. And I'll explain a little bit about that in a second, but I thought it would be good to start with the Options API first and just show you the basics of how that works. And then next week we'll follow it up with a dive into the Settings API. I see we've got some more folks coming in. We've got John from Chicago. Hi, John. And we've got, I'm going to try and pronounce your surname correctly. Aya Zudin from Nepal. Welcome. Adrian says, shameless plug for the event for Jonathan will be helping. It's a free 24 hour event out of mind, shameless plugs called the WordPress Accessibility Day. Register today. Did I mention it's free? And you can go to 2023.wpaccessibility.day. So yes, I do recommend going along to that. If you are free, it's on the 28th. I'm not mistaken, next week Friday. Adrian, is that correct? Next week, Thursday, next week Friday, somewhere around there. I can't think about my dates next Wednesday. Next Wednesday. Okay, got it. So please do check that out. And if you're interested in next, all things as a WordPress and all things accessibility, 100% free, go and check that out. I don't mind you plugging that at all. Okay, a couple of announcements. First of all, again, welcome to everybody who has joined and thank you to Tracy, who's co-hosting with me today. Tracy will be keeping an eye out for any questions, any problems, any issues. So thank you, Tracy, for doing that. I am sharing my screen at the moment. So if you can't see this announcement slide, please do let me know and I will re-enable the screen share. You can just pop a message in the chat if you can't see the screen, if you're just seeing like my face and the other participants' video screens, let us know and I'll just re-enable the screen share. If at any time the screen share disappears, just let me know and I'll re-enable. We are presenting in focus mode. So that means Tracy and I can see all of your videos but you can't see each other. That just creates a safe space where we have had some issues with Zoom bombing in the past. So this just helps to prevent that. You are as always welcome to ask questions. You're welcome to post your questions in the chat or you're welcome to unmute to ask questions. I don't mind folks using their microphones to ask questions if they want to. I know a lot of folks tend to leave themselves muted and that's okay too. And the chat is there if you want to post questions and I do take breaks and I come back and I read through the chat to follow up if there were any questions that I missed. All right. If you are wanting to code along with me today, please do get your local WordPress installation ready. If I am going too fast as always, please do let me know. I do tend to get a bit rushed sometimes. I tend to maybe jump ahead with the coding examples a bit too quickly sometimes. So please slow down if I'm not sharing anything quickly enough with you. Slow me down, let me know. We are recording this session and this will be posted to WordPress TV afterwards. So if you want to catch up on this later or if you want to watch it again, it will be posted to WordPress TV. I'm probably going to try and do it tonight because I have a bunch of things that I want to get through tomorrow. So I'll try and make sure that's uploaded this evening. And then lastly, the places where I recommend you go and check out for more educational content is learn.wordpress.org, which is the site that I spend most of my time creating content for. And then developer.wordpress.org slash news, which is the recently launched WordPress developer blog, all kinds of useful and interesting articles on there. So do go and check that out. Okay, our learning outcomes for today. As mentioned, we're going to be diving into the options API. We're going to be looking at what the options API is. We're going to look at what it's used for and what you as a plugin or theme developer should be using the options API for and what you shouldn't be using it for. We'll also chat about how to use it and we'll go through the four core functions that make up the options API. There are only four core functions that you need to worry about. We'll also have a brief chat about data types and how options are stored in the database and how differentiated types are converted based on how that's stored. And then we'll briefly chat about protected options and permissions related to options. That will just be a very quick overview of those two things. Okay, so I'm going to prepare myself for a quick break and I'm going to ask you in the chat on a scale of one to 10, sorry, one to 10. One to five, one being you don't know the options API very well at all, five being you know everything there is to know about the options API. Please let me know in the chat on a scale of one to 10 how well you know this topic. I'd like to get an idea for what the audience level of knowledge is on this one while I grab a quick sip of water and refresh my throat. Okay, we've got a couple of ones. We've got a zero to one. We've got a two, got another two. Okay, so most folks have probably heard about the options API or they've maybe seen it or used it. Maybe they understand that it's the word I'm looking for. It's the foundation underneath the settings pages. Adrienne says, nope. Okay, that's perfect. That would explain the zero to one. Okay, well, that's great. If you've never heard of the options API, that's wonderful. Perfect person to be here today. But some folks know something about it. So hopefully we'll be able to dive into it today and be able to explain to you what it does, how it works and how you can use it. Okay, very quickly. If you want to code along with me today, we're not going to be creating any plugins or themes today. We're going to be using one of my test bed files again. So if you want to code along with me, you will need a local WordPress installation, whatever platform you're using, local WPWP now, whatever you prefer to use is fine. You'll need a text editor. I'll be using VS code. You will need it. You don't have to have a way to access your WordPress database, but it will be helpful for you to see the data being stored in your database. And you can either use something like if you're, I know local WP and a few others there, I think they have PHP MyAdmin or Adminer installed by default. So you can use that. If you don't have those, there is a sort of plugin that I can recommend. It's called SQL Buddy. I have mentioned it before in these sessions. It's a plugin that you can install into your WordPress site and it allows you to browse and access the database. I don't recommend installing this plugin on any production sites. I only suggest installing it on either a local site or a development site that you're working with, or if you really need to inspect the database on a production site, install it, use it and then uninstall it because it could possibly open up your site to some kind of security issue because it is working with the database. So I'm going to open up my local WordPress site here. It is available to me at this learnpress.test URL. Here is my admin page. I'm going to install SQL Buddy quickly. I have already downloaded the plugin. Let me just deactivate that. That's something else that I'm working on. I have already downloaded the plugin and it's sitting on my desktops. I'm going to quickly just install it. I know that the plugin page has a little note that the plugin hasn't been updated with I think the last three versions of WordPress or whatever. I have actually reached out to WP Engine who now own this plugin and a friend of mine, Ian Poulson, who works there and just said to him, folks, you might want to get that updated because the plugin does still work. It doesn't need to be updated to keep up to date with WordPress. It does still work. But once the plugin is installed and activated, it creates an option in your tools menu called SQL Buddy or SQL Buddy if you want to be a little bit more correct. And then you can then browse through your database and you can view all the tables. You can click on one of the tables and you can see the data in the tables and that's a handy tool to use. So that's what I'm going to be using today. You're welcome to install it on your side as well if you want to follow along. And then lastly, a file to test the option API function calls. So this is a very simple PHP file that I've created. It's sitting on a guest.github.com. Guest is a way that you can share code with folks, simple snippets of code. And this is just a very simple PHP file that you can install into the root of your WordPress install and you can then run arbitrary bits of WordPress code in that file. So what I'm going to do to use this is I'm going to click on the raw button which will give me the raw text of this file. I'm going to copy all of this content and then I'm going to go into my VS Code setup. I'm just gonna make this size right quickly. I think I might already have this file in my root of my WordPress install from the last time we did this. So I'm just gonna check. Yes, there it is. So I'm going to delete WP test so that you can see me create the file. So inside the root of my WordPress install where I would find things like the index.php or the readme.html, I'm simply going to create a new file. I'm going to call it wp-test.php and I'm just going to paste the code from that snippet into this file. Once I have done that, I can browse to my local domain, whatever your local domain might be, forward slash and then call wp-test.php which allows me to browse directly to that file. And if I've set everything up correctly, I should get this learn WordPress title and then hello and the name of the site. So in this case, my site's name is learnpress. So it says hello, learnpress on that page. That's the file we're going to be working in today or I'm going to be working in today at least. I'm going to take another break if anybody else is setting this up on their side. If you need me to slow down and stop while you're doing that, let me know. But once that's all set up, if anybody is setting that up or if anybody's not setting that up and they're just, they're keen to get going, you're welcome to give me a thumbs up or a yes or a ready to go. If anybody wants me to stop, you're welcome to ask me to slow down while you set that up. I'm going to have some coffee while I do that. Yeah, Adrian's good to go. We're going to just pop back over to my slides here. And this is my let's go screen. I love the picture of the lady with all the code over her face. So the documentation that we're going to work with today, I'm going to share the link in the chat but I'm also going to show you how I get there is if you go to developer.wordpress.org, that is the developer documentation hub. It's also known as Dev Hub. That was the nickname for the new developer hub when it was migrated from the old codex. It's also where, as I mentioned earlier, if you go developer.wordpress.org news, you'll find the developer blog. So that's a good way to remember that. But the developer hub, developer resources, as you can see the title, is basically where all the documentation for WordPress developers resides. It has the code reference, the coding standards, everything about the block editor, all of the common APIs, everything about developing themes, developing plugins, the REST API, WPC Ally, advanced administration, all kinds of other fun things. So if you go to developer.wordpress.org and you click on the utilize APIs button, you will see the list of common APIs down the left here. If you've been attending these workshops for the last few weeks, you will have noticed that the trend has been to cover these common APIs. My goal is to have a workshop and hopefully a tutorial for every single one of these eventually. I'm trying to get that done by the end of the year, but I didn't know if we're gonna get that right. But today about halfway down the page, we've got the options API. So if you click on that, that'll take you to the link that I shared earlier in the chat. And that's the page we will be talking about today. And you will see the first thing it says in the overview is that the options API is a simple and standardized way of storing data in the database. Now, if you've never heard of the options API before in your life, you may however have used it, even if you haven't heard of it. And if you go into your WordPress site and if you click on any of the settings screens. So for example, the general settings, the reading settings, the writing settings, the discussion settings, if you've ever changed any one of those settings, you are effectively writing data to a specific table in the database and you are using the options API underneath the hood when you're storing this data. So I'm gonna leave my settings page over here and I'm also going to open up the SQL buddy page so we can have them both side by side. And you will see right at the top of my general settings, there is the site title and the site tagline and the WordPress address and the site address. It also contains the admin email address. Now, if you're setting up WordPress, if you remember the favor of Ms. Five Minutes install, a lot of this data you set up when you set WordPress up. That data gets stored into what's known as the WP options table. The prefix might be different on your local install depending on how your site is configured, but it's always going to be the prefix, whatever that is, the default is WP underscore and then the word options. You'll see that currently that table has 154 records. Now this is a fairly new WordPress site. I set this up about two weeks ago. So by default, there are about 150 records in that table. If I click on that table, you will see that the first two options are site URL and the home URL, as well as the next two are the blog name and the blog description. So that ties up perfectly with those four settings there. So every single setting that exists as a setting on the setting screens is stored as an option in the options table. The settings API that I mentioned earlier is the API that manages what these screens look like. So it determines how the label appears, how the thing is stored, what happens when you, if I scroll to the bottom when you hit the save changes button, that all is the settings API. And then once you save those changes, the process of writing the data to the options table is where the options API comes in. So the options API has four core functions that allow you to read, write, update and delete any one of these options. Okay, so that's a very brief overview of the options API. What I wanted to also mention is that I'm just scrolling back through my notes here very quickly. Sorry, one second folks. I managed to lose my notes. There we go. So the thing about the options table is that besides storing data about the WordPress site, in this case, blog name, site name, blog description, all of those kinds of things, you can also use this to store data specific to your plugin or theme. So to do that, I want to show you a plugin on my personal site. I don't mind quickly logging into the dashboard of my site because it's just a blog. There's no private or personal information there. But in my personal site, I am using a plugin called seriously simple podcasting. Let me show you where it is here. Seriously simple podcasting. It's the plugin that I sort of cut my WordPress plugin developer teeth on. When I was first a WordPress developer, I worked for the company for a number of years, but it's basically a plugin that allows you to turn your WordPress blog or site into a podcast hosted site. So you can host podcasts on your site. And if I go to this podcasting menu item here, you'll see that there is a settings option that I can click on. And these settings are specific to managing my podcast. So I can do things like set the podcast post type. I can do things like there's a player tab and I can set the media player locations. I can set the media player position. So these settings are very specific to how the plugin functions, how it renders the certain podcast related data on the front end. And it wouldn't make sense for me to store this data in any of the content tables like the post table or the comments or the users table. So these settings or these options, if you will, would then be stored in the options table. So as a plugin developer or as a theme developer, if you are ever needing to store any kind of settings for your plugin or theme, you would use the settings API and the options API to store that data into the options table. Okay, let's have a look at the options table and let's see what it looks like, how it's structured and the basics of how it works. You will see that options has four fields, the options table. It has an option ID, an option name, an option value and a field called autoload. Option ID is a numeric field. It starts with one and just keeps going until however many that it can allow and it's some large number. Option name is a string or a text field. So you can only store text in that field. Option value is also a text field. So you'll notice that all of these are actually, this might be a number one, but it's actually the string representation of one. And then autoload is either a yes or a no. What autoload does is there's a specific function in WordPress that I want to share with you. I've actually got it loaded here in the resources slide. I'm going to pop it open into my window and I will share it with you in the chat. WP load all options is a function that fires very, very early on in the WordPress request lifecycle. And what it basically does is it goes and queries the options table, where were we? And it requests or selects every single option from the options table that has autoload set to yes. It then caches that data. So in other words, it stores it in a temporary location so that for the rest of the WordPress request, so if you're requesting a page on the front end, if you're requesting a post, if you're requesting a list of posts, whatever you're requesting, if ever you need to call one of these options to perform a specific functionality, it gets that data from the cached version, not from the database. So what that means is, let's say for example, if we think about the podcast player setting that I mentioned earlier, I probably shouldn't have overwritten that page because now we want to see it. Media player position, for example. So if I set my media player locations, it must display the media player in the full content and in the excerpt, for example, which I've done here. And then I say I want the player to show it below the content. When I go and render a list of podcast episodes, and I actually, I don't actually know if I can do that on my site because I've done so many things over the years that it might not be possible, but let's try. Let's see if I can go to the podcast archive. It might break. It's actually gonna redirect somewhere else, so that's not gonna work. I'm busy fiddling with my podcast. But if I wanted to render the list of podcast episodes, it would then have to check, every time the excerpt is displayed, it would have to check, where do I want to show the media player? So it would have to make a request and say, what is the value for that option say? And if I have 10 or 20 podcast episodes on the archive page, if the cached version didn't exist, it would have to make a database request every single time to get that value. So that's the reason this autoload option exists, and that's the reason the WP load all options function exists. So it just does that call once it runs one query to the database, caches those options so that they're available to the rest of WordPress. And then any way where data is being rendered or at least to call those options, it can then pull them from the cached version, not the database version. Okay, I'm gonna take a break there and just check if anybody has any questions around all of that, before we dive into how this actually works in a real world environment. Sorry folks, I just bashed my microphone there. All right, I don't see any questions, so I'm going to move on and let's get into how we actually use the options API. So I'm going to close a couple of these tabs, honestly, because they distract me while I'm trying to present. We'll leave SQL buddy open, we can leave the settings open, we'll close the plugin, and we've got the slides. Okay. So if we scroll down onto this options page in the common API handbooks, you will see the function references there. There are, I'm going to focus on the first two functions here and these two functions here, I will dive into these two and these two in a second, but essentially there are four core functions. There is an add option function, a delete option function, an update option function, and a get option function. And each function does exactly what you think it does based on the name. Add option adds an option to the database, delete option deletes that option, update option will update an option already existing in the database with a small addition, which I'll get to in a second and get option will fetch the value for that option. You will also see on this page, there are the add site option and delete site option functions, and the get site option and update site option functions. Those specifically are used in a multi site environment. So if you are building a plugin that you want to work specifically on a multi site, you would probably want to use add site option and delete site option and get an update site option functions instead of the standard add delete and get an update. And the way that works is it only works in the scope of a specific site on a multi site network. If you have a look at the add site option function, for example, you will see that if we go into the code, it calls this add network option function and the rest of the site option functions do work like that. I'm going to focus purely on the, if you're working on a single site functions today, multi site is a different piece altogether. We've chatted about multi site, but I'm going to focus on those functions specifically for today. So the first function we can chat about is the add option function. I'm going to be saying the words option and function a lot in this workshop. So I apologize if those words get boring to you. Add option is a fairly simple function. It takes four parameters. The first one is the option that you want to store it as. If we have a look at the database table, it's the option name effectively. The second one is the value that you want to store. You'll notice that the function definition says it is a mixed value. So I'll dive into that in a second. Then there is a, and I don't see this a lot in WordPress, but then there is a deprecated parameter. And if you scroll down into this documentation, you'll actually say it just says not used anymore. So it's a parameter that if you're going to use the parameter after it, you have to pass an empty string to this parameter. And then the fourth parameter is the autoload parameter. It defaults to yes. It does accept no to disable this for legacy reasons, but it is generally recommended that if you're using these options in your plugins and themes, you're going to be using them on the front end. Leave it to default yes. It would only be in very specific use cases that you would want to pass that as no. So the most sort of straightforward way that you would typically see add option used is somebody will pass in the option name and the option value. So let's have a look at what that might look like. I'm going to go into my test site. You'll actually see I'm already using get option there. So we're going to kill all of this quickly. And I'm going to say add option, going to open up my brackets for my function. And then I'm just going to give it a name. The name that I'm specifying can be anything that I decide. So I'm going to just say here WP underscore learn underscore test option. That's just the name that we're using today. I'm going to put in a comma and then I'm going to pass in a value. And I'm just going to say test value. Now you'll notice that I'm using underscores to sort of concatenate words or string them together in the option name. You can, I think also use hyphens. I'm not sure, but I prefer to use underscores. You could also just use all one word like this. But I find separating it with an underscore just makes it easier to read. The value, however, is a string. So I can include spaces. I can generally include the special characters like exclamation marks and all that kind of thing. And it will then store that value to the table. So what I'm going to just do here is I'm just going to say echo option added. We're going to run this. We're going to make sure that it's been added and I'll show you how it's stored. So that's the simple code I'm going to use. I'm going to pop this code in the chat if anybody wants to copy it into their test but let's run that and let's see what happens. So there I've run my code. I get the message option added. Everything seems to be fine. If I go into SQL buddy and I refresh the options table, I'm actually going to just refresh it here. Now I need to go looking for that option. And I should be, let me just close this guy here. Often what I will do is I will just jump to the end of the table and then you'll see it there. WP learn test option is sitting there because the table, generally a nice SQL table, the records are ordered by ID. So generally if you've added a new option it'll be the very last option in your table. But there it is WP learn test option. There is the test value. You can see the exclamation mark and you'll see the auto load has been passed by default as true. And that's as simple as that. That's how you add an option. Okay. Any questions on all of that before we move on to how we would get an option? Actually something else first before we talk about get an option. We don't seem to have questions. Now some of you might be looking at my screen and you might be seeing this weird text over here. You might be wondering what that is. And there's this one over here as well. It's not a simple string. The options table or at least PHP, should I say supports something called serialized data. I'm gonna open up the PHP manual on serialized data quickly. It's probably gonna just be the serialized function but that's not the PHP manual serialized. There we go. So PHP has a function called serialize. And what serialize does is it takes either a PHP, a more complex variable like an array or an object and it converts it into a string format. I've mentioned this before in other workshops but it's a way of storing more complex data in simple tables. When you use add option, you can also store. So I've lost my Mac OS bar here. I don't know why things have changed on me. That's annoying. Let me get no, I don't want Mac whisper. I want, sorry folks. If you think it's just gone weird on me here. I want visual code studio back. There we go. So when you add an option you can also add an array or an object of data. So let me show you what I mean by an array. So an array, I'm gonna say my option array. In PHP you can use the array keyword or you can use also the square brackets. I prefer the array keyword. And then you can store multiple items in an array. If you've never seen arrays before don't worry too much about them now but it's basically a way of storing multiple bits of data in one variable. So I can say item one and then I can just do that a couple of times. Let's go item one, item two, and item three, and item one, and item two, and item three. And then I can store this array as an option. So what I'm going to do is I'm going to update this. I'm gonna say WP learn test option array. So I'm gonna create a new option and I'm gonna pass the array directly into that function. And let's just update this to say array option added. So we know it's the new code and let's run this and see what happens. Again, my tool bar, my macOS tool bar has gone off screen so I'm gonna have to switch over. So let's go back to that code. Let's run it. There it is, array option added. Let's go back to SQL body and refresh the page. And if we go to the very last, sorry folks get that out of the way. Very last page, there it is. WP learn test option array and there is the serialized array of data. If I open this up, you can see that the way it's stored is basically it stores the, if it's an array it stores A for the array and then it stores how many items were in the array. And then it stores additional information about how many string characters for the first one, the second one, the third one, all that kind of thing. And you can store, so you can store arrays in that way. You can also store this one, for example, this is an object. And you'll see it's storing it as an object, an O it's of a type of standard class. And then there's again more information that's stored against that. So you can just pass in either an array or an object. Let me share that, sorry folks. Let me share that code with you if you wanna work with that. You can just store either an array or an object in an option. WordPress will automatically take that data. It'll realize that it's not a plain string. It'll serialize it and then store it into the database for you to then use later on. Okay, any questions around that? Well, I try and get my Mac OS toolbar back. I'm actually not even sure how it went away in the first place. So it's frustrating to say the least. I know there's a way that you can tell it to show and hide which I stopped doing a while back. Let me do that. Oh, there we go. Okay, let me do that. Yay, it's back. All right. Okay, we don't have any questions. So let's move on to our next function for today. So the next function that it makes sense to now look at using is how do we fetch the array from the data or at least the variable, the value, whether it's a string and array. That would be, if we go back to the docs, let me move this up the way. Zoom is missing with my head today. That would be the get option function. So get option as the function name describes just fetches the option from the database. Tracy says that explains the mixed type in the function definition. Correct, absolutely. You can pass in a string and array and objects. It'll know what to do with it. So you'll see in get option, you can say what the option name is and then there is another mixed, sorry, I'm gonna turn this off. Because it's bugging me. It's this AI tool that I use and I want to, I need to just remove it for now because it's getting in my way today. Get option, there we go. So get option, the first parameter is the option name and the second parameter is what's known as the default value. So let me show you how it works without the default value first and then we'll chat about the default value. If we go back here and if we have a look, sorry, before we do that, let's have a look, learn test option and learn test option array. So let's get them from the database. So what I can do here is I can say echo, get option and I simply need to pass in the option name that I want to fetch. Wordpress will then go and fetch that option for me and because I'm using echo, it will echo it to the screen. What I can also do is I can fetch the array. So what I'm going to do there is I'm going to echo some PRE tags just so that it's nicely pre-formatted. And then I'm going to use a function that you may have seen me use before, something called print R. It's a way of printing out arrays or objects. And then I'm just going to say get that option from the database. I want the string at the top. So let's get the string option there and we'll get the array option just below that. So that's what the code looks like. And there we go. All right, let me pop this into the chat. Adrian says AI's real function is to noise, agreed. All right, so that's the code I'm using. So the first one is going to fetch the value for the WP learn test option based on that option name that I've passed. The second one will get the value of the array and then just I'll put it on screen. So let us see what that does for us if we go back here and refresh it. There we go, test value was stored as the first one. So we get that back and then you'll see the second one is returned as an array. So because it's stored as serialized data when we fetch it from the database, WordPress goes, okay, this is serialized data. I need to unserialize it, turn it back into its original format whether it was an array or an object or whatever it was and then give that back to you as some data that you can work with. And you will often see add option and get option are used quite a bit in plugins where developers are setting up options and then using them on the front end in the Seriously Simple Podcasting example I gave you earlier, I would have stored that media player location option and then when it's rendering as it loops through it'll be a get option call, get the media player option based on the media player option, where do we show it either above or below? Okay, then very quickly, let's chat about this default value. So when you want to use the default value it's generally when you're working with an option that may or may not be set by the user. So let me explain with a little bit of an example using that media player location, what I'm talking about. And I'm gonna use a bit of what we call pseudo code to kind of explain that. So I'm gonna create some comments here and I'm gonna say, let's say you fetched all of the podcast episodes from the database and we'll just say fetched from database. This is not actual code, but it kind of gives us an idea. Then you might do something like loop through using a for each loop. You might do something like that and you might say loop through the podcast episodes and then you might want to start echoing out. So you might say something like so it'd be podcast episodes as episode for example and then you might want to echo the episode player for example. So I'm just gonna use this as code so that's the player that's being echoed. But then based on, and you might also want to echo the excerpts, based on that setting we chatted about earlier whether the player should appear above or below the excerpt, you're gonna need to do some kind of code to check that. So then you would say, okay, fine. I've stored this option and for the purposes of this test, we're just gonna say that this option is called media. I don't know what it actually is, I haven't checked the code, but let's just say it's stored under media player location and it's either at the word above or the word below. So what I would then do is I would say get, I would do that above the loop because I'm not gonna want to do it every time. I would say media layer location equals get option and I would pass in the option name which happens to be media player location and that's gonna give me either the word above or the word below. But what if that option hasn't been added to the database yet? So what do I mean by that? Well, the setting was in the plugin settings but for it to be saved to the database either the plugin has to add that option on like a plugin activation or something like that or the user has to store that setting. So if one of those two things haven't happened then there won't be a value in the database for this media player location option. So now I have a problem because now if I return, if I get that option, I'm gonna get back an empty string or a false value and then I don't know what to do with the excerpt. That's where the default value comes in. So when I pass in a default value and I will pass in whatever the sort of default is if the user hasn't said anything. So in this case, I'm gonna say the default is above. Then there will always be something returned to media player location. So if the plugin hasn't set it up, if the user hasn't changed the settings or if something's gone wrong with the database and that option has been deleted by mistake, which can happen. Sometimes users will clean up their database and they'll delete things and they don't realize that that's related to what they're doing. It could get deleted by mistake. At least now in my code, I can say something like, well, if the media player location is equal to the word above, then I render my player first and then my excerpt. Otherwise, if not, then I do it the other way around. I do my excerpt first and then I do my player. And so using the default value is a way to effectively save a little bit of time and stress because otherwise I would have had to, in the plugin activation, I would have had to run an add option to add media player location with the default value of above so that when I have to fetch it on the front end, I can get a value of above back. It's actually just a lot easier just to say, well, the minute I get this option, if there isn't something stored in the database, give it a default value anyway so that above gets passed into that media player location variable so that when I'm doing my checks further down, it at least has some value because if it didn't, all of this code would fail and nothing would be rendered on the front end. Okay, so that's what the default value is and you'll get option call. I do recommend using the default value. It doesn't add any overhead into your code because if there is a value in the database, the default just doesn't get used. If there isn't a value, then at least you return the default. So something is returned at least. So when you're working with options and you're using options on the front end to perform some kind of functionality, I do recommend setting a default value so that you know you're going to get something. Okay, so that's the default value on get option. That's how add option and get option works. I'm gonna take another break and grab some coffee. If anybody has any questions, otherwise we're going to very quickly move through update and delete and then cover the last few items on my list today. Going to also add that we're probably gonna go a little bit over time. So I do apologize to folks who are stuck to the hour, but you can and we'll be able to see those bits on WordPress TV once I upload the video. All right, it doesn't look like there are questions at this point in time. I'm just gonna mention this briefly. I once did a live stream and I live streamed for about 45 minutes before I realized that I hadn't started the live stream. And I wondered why nobody was chatting in the live chat or asking questions. So when I don't see questions, it does make me a little bit nervous, but I do know that Adrian is there on video and I do know that other folks are there. So it just means there are no questions today, which is great. Okay, I'm not gonna dive into updates and delete at the moment. They are fairly explanatory. Update will update the option and it's exactly the same parameters as add. Stuart's present, thank you Stuart. It's exactly the same parameters as add. You pass in your option name as the first parameter, your new value as the second parameter, and then you can change the auto load value as either true or false to update the auto loading. So that allows you to update an option. I don't think I need to dive into that. It's pretty straightforward. You pass in the current option name, the new value and it updates. The thing that I do wanna mention though, over here, if the option does not exist, it will be created. Now, this is one that is slightly contentious in sort of developer circles. This is one of those things where WordPress prefers decisions, not options. So WordPress prefers to say, well, if somebody writes an update option function call and that update isn't there, they probably assumed it would be there, so let's create it anyway, okay? And so the reason I mention this is because I want you to be aware of it. Some developers, what they will do is they will actually sort of shortcut and they will never use the add option function. They will always just use update option, whether they want to add it or update it because they know updating, calling the update option will add it anyway. So it's an interesting little thing about how WordPress works. I personally don't have an opinion about it because the mentality around it comes from the way PHP works back in those days where if something was requested to be done and it wasn't there, then PHP would kind of just do it for you as well. So it's kind of something I'm used to. But those folks that are very strict about the fact that functions should only do one thing. So if you're calling update, it should only update and if the variable, sorry, if the option isn't there, it should show an error, not add it. There is that kind of argument in developer circles. It's just good to know. It's good to be aware of. My personal preference, when I am using the settings API to save settings, I will use updates in that process of saving those settings. But any options that are important, I will actually, in a plugin initialization step or plugin activation, I'll actually add those options with their defaults. That's just a personal preference. You don't have to do it. But it's just good to be aware of these things as you go along. And then last but not least, delete option, there really isn't much to explain there. There is any one parameter, the option name. You say delete option, give it the option name and it will delete that option from the database. It's as simple as that. It doesn't have any other parameters. It returns true or false. If it's been deleted or if it hasn't, and that's all that delete option does. There's really not much we need to talk about there. Okay, any questions around add option, update option, delete option or get option? There are very simple functions. There's not a lot to really dive into there. There's a few caveats, which some of which we've discussed already. But it's one of the easiest to understand and easiest to use APIs in the WordPress system. So not really a lot of complex and difficult information there. So if you have any questions around those four functions now, you can let me know. Otherwise, we will dive into the last two topics that I wanted to just chat about today. I'm gonna close some windows here. That one can stay there, that one can stay there. This one can go away. And then those are my slides. All right. Adrian says, is there an interface for this in the dashboard once it has been added? Great question, Adrian. Thank you for that. The answer is no. You have to go and bullet yourself. So once an option has been added to the database, it's just in the database. You have to then build using the settings API, you'll have to build interface for your plugin or for your theme, which we're gonna do next week. So next week, we're gonna use the settings API to build a settings page for a plugin, similar to the podcasting settings that I showed you. So there is one slight caveat to that. And I think it's a good idea to mention it now, seeing as you've asked that question. But there is this hidden sort of page in the WordPress dashboard, which a lot of folks don't know about. It's right at the bottom of this page. So scroll right down to the bottom of the options page. There is an all settings screen. There's no link to it. You can't access it anyway. But if you copy this URL, wpadmin forward slash options.php and you go to your WordPress install and you place it at the end of your local or your domain or whatever. That is a page that will list all the options in your WordPress site. And you'll see right at the top, it says this page allows direct access to your site settings. You can break things here, please be cautious. But if I scroll right to the bottom of this page, you will see there is my wp learn test option that I created. There is the option array as well. So there is one place where there is sort of some default UI to access these things. But as you can see, it's not very user-friendly. It literally just uses the option name as the label and then has a field for the text. You can't access the serialized data. It just has this grayed out box that says serialized data. So you have to, if you want, so let me give you a good example of what a serialized data option would look like. I don't know if there's one here. No, there's not one here, but sometimes you will have, I wonder if there's one, I wanna show you, I wanna try and show you an option of where there might be some serialized data stored. Let me see if there's one in the podcast settings. I seem to recall we had, so this is a good one, podcast post types. So when the user clicks on these, basically the setting allows you to say which custom post types can also be considered part of the podcast, and therefore you can apply episode details to them. So here you'll see it's a bunch of tick boxes. And then when this is stored, it's stored as an array with all of these options and then either the true or false against that option, and then that's stored in the database. And then when the option is retrieved, when this podcast post type setting is displayed, it loops through that array and then ticks or unticks the fields as it goes through. So that's one way that arrays get unserialized and used, but that's where the settings API comes in to be able to build this data, which as I mentioned, will be covering next week. So thank you for that. And then Adrian says, I've seen serialized it listed as a way to clear out plugins when you can't get into the dashboard. Yes, that's another good example. Let me go back to my local site. Let me open up SQL buddy. There is, and this is the cool thing about if you get to know what's happening in the options table, there is a, try and remember how to do a query in SQL buddy. Yeah, that's visible columns. Here we go. There is a, and I'm gonna use contains and I think it's the word active plugins. So let's see if we can find it. Yes, there is an active plugins option that is stored in your options table. And it stores an array of all the plugins that have been activated. If you delete or clear out this option value here, it will then effectively unactivate all of those plugins the next time WordPress loads and you can then recover crash sites like that. So all of those kinds of settings are in your options table getting to know the options table as a whole workshop on its own, but getting to know what data is stored in there and how it's used by WordPress is a very good skill for WordPress developers to have. You will see in this options documentation that I shared with you, there is actually a list of all of these sort of default fields that WordPress sets up that there are 154 odd records that we started off with. It stores your permalink structure. It stores things about how comments work, whole bunch of things. So if you ever have some time diving into those settings and see what they do, it is amazing how much gets stored in the options table of your default WordPress site. All right, while we're on the topic of those that actually goes nicely into my next topic. Yes, I'm going to open up the, yeah, the list of deeper options you can find here in the option reference in the codex. I'm gonna share that with you. That's good reading. That's in the old WordPress codex. If you open up, let's open up add option, for example. And let's just dive into the documentation there. You will see that it says existing options will not be updated for add option. That makes sense. And checks are performed to ensure that you aren't adding a protected WordPress option. So in other words, as a plugin developer, you can't add the active plugins option yourself. Only WordPress can manage that. So that's a way to make sure that developers don't break core WordPress functionality. So it's a good thing to know. It'll probably never be a common problem in your life. But if you're ever building a plugin or a theme and you're trying to store an option and it's not saving and you can't figure out why, check if it's a protected option because that could be a reason. Then the other thing I wanted to mention is permissions. So I don't think they mentioned it here, but I'm going to go back to the update option function because I know they mentioned there. You will see here, it says an update option. This function is designed to work with or without a logged in user. Now, yesterday when I was preparing for this workshop, I went back to the add option page and you can see that the code for the add option function is listed here in the source. And if you go through this code and all of the other four functions in the options API, there is no check for whether or not the user performing this action has permission to do so. Why is this important? Well, if you're calling add option, update option or delete option through something like an Ajax call or something outside of the WordPress dashboard, you possibly expose your site to somebody else accessing that functionality and possibly adding or updating or deleting options you don't want them to. Now, the nice thing is because it checks against protected WordPress options, people can't mess with your core WordPress site but they could break your plugin or theme functionality. So when you're working with plugins or themes, if you're using specifically add option and update option and delete option outside of the dashboard, it's a good idea to use the built-in WordPress user permission system. The main function that you can use there is the current user can function to check does the current user have the option to manage options? Sorry, the permission. That's a whole nother topic. We did do a workshop on user permissions. I also did a tutorial on working with user permissions but essentially I'm gonna show you in the code very quickly. If you're wanting to call add option or update option or whatever and you're not sure whether or not the current user has those permissions, you can very simply do something like this. You can say if current user can and the permission is actually called manage options and generally only administrators have that permission. So you can say if current user can manage options, then I can add updates or delete my option. The other way you can do it is you could do the what's known as sort of the early check or the inverse of that. You can say if not current user can manage options and then you could stop execution here and then I can't spell today and then show some kind of message and say sorry, well, you don't have the option to do this and stop execution right there. So whenever you're working with these things make sure that your user has those permissions. It's a good idea to check even if you are in the admin because even in the admin dashboard it might be possible for a non-administrator user to somehow access that field if code isn't done correctly. So whenever you're adding options and updating options, make sure you do a current user can check beforehand. And then that way you know that the option won't be updated or added by anybody you don't want to be able to do that. All right, that is my bit for today. That's everything I wanted to cover. I do recommend reading through this options API page in the developer handbook to kind of dive more into that detail. Does anybody have any other questions about all of this before we wrap up today? And I've just made it on time. So if you do have questions, that's fine. I don't mind going over but I have just just made it in time. So I'm quite happy about that. All right, there don't seem to be a lot of questions. That's wonderful. I'm glad that hopefully something was useful today. As I mentioned, next week we're going to be diving into the settings API. So I'm going to be showing you how to create those settings pages using the options API underneath. We'll take a little bit of a simple plug-in. We'll build in some options. We'll save some settings pages. I'll show you how to work with it. Thank you all for your time. It was lovely to see you all here this Thursday. Enjoy the rest of your Thursday and the rest of your week and I'll see you all next week. Bye-bye.