mixster
03-20-2008, 05:43 PM
Welcome to the 'Write your own SRLStats' tutorial
This tutorial will be broken into about 4 or 5 or 6 parts (not sure yet as I'm writing it a section at a time) and will help you understand how SRL Stats works and help you involve php and databases in your scripts to make them that bit more uber 1337 as well as setup your own basic SRL Stats to show the possibilites of Scar, php and databases. In this first part, I will be showing you how to setup a basic php script and getting it to return a value back to Scar and basic version checking to your PHP file so it can be useful to the common user. Also, mods, if you feel this should go in another section, then feel free to move it - I thought it should go here because it has very simple code, but the idea in principle is more advanced than a basic user, so :spongebob:
First of all, you must have webhosting of some kind. You can get free webhosting and if you're not sure where, then I don't have any direct links, but I can suggest something - *cough* google *cough* - and most free webhosting will also come with a database and a file uploader so you don't need a program like Microsoft FrontPage or Dreamweaver (ftw!) and can instead just write it in notepad and save it with .php on the end (make sure you choose 'All Files' in the dropdown in save/as otherwise it will save it as .php.txt). If you need more help with webhost's or uploading etc. feel free to PM me or post in this topic (though check the topic before posting or pm'ing as your qeustion may have already been answered!).
Now, onto the tutorial!
We will be starting out by making a Scar function that returns the contents of a webpage. Remember to replace all '{url}'s with the appropriate url to your php page. Now, most people will know about 'GetPage()', but we won't be using that for this tutorial as it doesn't allow us to output anything, so what we will be using instead is 'PostHTTPPageEx'. It is a lot more complex to set up, but it is worth it in the long run with what it allows us to do. If you look it up in the Scar library (F1), then you will find out it needs the following variables: Client - Integer and Url - string and also outputs a string. Well, what's Client? It's a variable that holds all the extra data to be sent to a webpage and needs to be set up before and cleared afterwards (well, it doesn't need to, but it should be) and for this tutorial, I will be using 'MyClient' simply because when I learnt about it, it seemed like an obvious choice. So to set it up we just assign our variable to 'InitializeHTTPClient(False, False);' The first False relates to handling Cookies and the second to handling Redirects. Unless you're an advanced php scripter, then you will probably have no idea how to use either, so it's better just to leave them to false for now. With that bit, we now have our first variable set up and the second one we can leave until the php file is up. So with that, we just have to clear the Client using 'FreeHTTPClient(MyClient);' replacing 'MyClient' with the variable you used for the client if it differs. With all that sorted, we just need to make it so that the result is assigned to PostHTTPPageEx so our function returns the "webpage" (more on that in a bit) and we're done! If you were following the scripting, you should get something like the following. If you're just reading through, make sure you go over the general layout a few times as it will be used repeatedly for the rest of the tutorial.
function ReturnPage: string;
var
MyClient: integer;
begin
MyClient := InitializeHTTPClient(False, False);
AddPostVariable(MyClient, 'pName', 'pValue'); // Ignore this for now, it only stops an error from happening
Result := PostHTTPPageEx(MyClient, {url});
FreeHTTPClient(MyClient);
end;
You can test the script by WriteLn'ing the function using 'http://google.com' as the url and you should get 'HTTP/1.0 501 Not Implemented' in the debug box (it sounds like an error, and it is, but it means that it's working). With that sorted, we just need to know how information is received by PostHTTPPageEx. Well, it takes in all of the source that is shown on the webpage (so if you went to view->source now, that's what would be returned by this page). So, we know how data is received, now we just need to know how to output code in php. Now, if you know basic php, then feel free to skip the next paragraph.
When writing a php file, you have to tell it when to start reading the code as php code with php tags. The open tag, which tells it to read as php code, is '<?php' and with the closing tag, which tells it stop reading the code as php, being '?>'. The second thing to know, is that every command has to be terminated with a semi-colon - ; - otherwise it will give you an error. The next thing to learn is how to output code. As php doesn't write out everything in it as code, it has to have a special command to tell it when to - just like WriteLn does - and that is 'echo'. It's very easy to remember 'echo' when you think of it as 'echo'ing what it is submitted to it. Unlike Scar though, most php commands (including echo) don't need parenthesis enclosed around it, so you can just put echo 'cheese'; to write out cheese and you can also do echo('cheese'); - neither is wrong, but practially all php scripters reserve parenthesis for mathematical uses. Also, you can use apostraphes (' ') or quote marks (" ") to mark strings, which makes things a lot easier with longer or more complex strings as you don't have to remember to double up your apostraphes if you use quote marks. Next, instead of using + to indicate when to join strings together, you use periods - . - which ties in nicely with my next point that php supports flexible variables. It means that you can assign a variable with a number in a string (like '2') and then add it to another number! It also means no more IntToStr's or StrToInt's or declarations (yes, no need to declare variables in a var section) and all you have to do is make sure you put a dollar sign ($) before variables (though always remember to double-check names)! For my last point for this bit, the assignment and comparatives are slightly in different in php. = is the assigner instead of := and .= adds onto a string, (so you can do string := 'rawr'; string .= '2'; and string will hold a value of 'rawr2') which can be very handy, though not so much in this tutorial for now.
Now with that bit of knowledge under your belt, we can make the absolute simplest way to use php usefully in your script, and that is a version checker that will also give you a little taste of php. The starting point of it will be the php open and close tags (<?php and ?>). After that, we will use a variable called $version (remember the $!) and assign it a value of 1 for this file for now. After that, we want to 'echo' the value of $version, which means that the source will have the value of $version, which is what PostHTTPPageEx will return to Result in our Scar function. So, you should have the following php file so far:
<?php
$version = 1;
echo $version;
?>
I know it doesn't look very classy or complex, but it is a start. You can test it now if you want by uploading it to your host (make sure it has a .php file extension) and fill in the url in your Scar function and you should see a popup asking for permission to access the file, then a '1' should appear in your debug box if you tell it it WriteLn the function (so 'WriteLn(ReturnPage);'). Well done, you have now made a simple function, but one that will grow in power as you learn more.
Now, I did promise you a version checker, and I am here to please you. What you could do is make the version checking bit in the Scar script, but where's the fun in that? So what I will be teaching you now is how to make an 'if' in php. It is more or less the same as in Scar, except with slight differences. It still has the basic syntax of 'if(Exp1 Comp Exp2)' (I'm sorry to say you MUST have parenthesis for if's check in php) which returns a true or false, depending on the expressions (Exp1 and Exp2) and the comparative (Comp). After that it differs slightly. Instead of having 'then' and 'begin', you just use an open curly brace - { - and you use a closing curly brace as the 'end;' - } with all code lines going in between them and you must use both ( { } ) regardless of length (so even with just 1 line commands, though with it being so short, it's hard to complain) . 'else' works pretty much the same - goes after the end (no more worrying about removing the semi-colon after the end!) and 'else if' works just like an else then an if (as you would assume). The only comparatives you need to know for now are: == which is equal to (as we can't use = which is the assigner), != which is not equal to for everything except numbers, <> which is not equal to for numbers and < or > which is the greater than or less than sign which works the same as in Scar.
So with that done, we just have to work out how to send information from our Scar script to our php file. The possible ways are using Get and Post. Post is a much more secure way that is often present in forms (such as a login form), while Get is actually visible and easily changable, but why use Get? Well, it means you can save a webpage in an almost exact format. Forums will often use it to store the topic or post, which means you can bookmark an exact page as the Get variable is stored along with it! For this, we will be using Post as the security will mean that outside users can't access the details and we already have POSTHTTPPageEx pretty much setup. The only thing to explain is how to add Post variables to a client. Well, we already have one setup! The 'AddPostVariable(MyClient, 'pName', 'pValue');' adds a Post variable to the client MyClient, with the variable being named pName and its value being pValue. So all we have to do is adjust it to our needs. As we're checking versions, SVersion sounds like a good name for it (with the 'S' referring to Script or Scar) and a value of '1' will do for now. So, with our variable set up, let's use it in our php script using our well known if else we just learnt! But wait, how do we access post variables, because they aren't sent as $SVersion, but instead as $_POST['SVersion']. Now this may confuse you, but php supports arrays with string indexes as well as numbers, while in scar you can only have arr[0], arr[1] etc. you can have arr[0], arr['donkey'] in php, so how cool is that? Now is the time to advance! So what we want to do is check to see if $_POST['SVersion'] is equal to $version and if it is, then we want to output 'true', otherwise we want to output 'false' - yes I am going to be changing our Scar function to output a boolean, so you better watch out! Now you should be able to code this with what you've learnt, but don't worry if you can't do it as it can be hard to pick up a new language, so that's why I'm here!
<?php
$version = 1;
if($_POST['SVersion'] == $version)
// Flexible variables means we don't have to convert the Post var!
// and yes, // = comments in php too!
{
echo 'true';
}
else
{
echo 'false';
}
?>
So, we have our php set up and all we need to do is convert our Scar to work with a boolean as well. I'll also be changing the name to 'CheckVersion' and make it output a boolean, so if you're coding along, be sure to do that quickly. Done? OK, next step is to use a valuable conversion function when using php called 'StrToBoolDef' which will convert the php files outputted code into a boolean and if it isn't a valid boolean, then it returns a default boolean, which gives us a nice output for our function. So, you should have a Scar function resembling this:
function CheckVersion: boolean;
var
MyClient: integer;
begin
MyClient := InitializeHTTPClient(False, False);
AddPostVariable(MyClient, 'SVersion', '1');
Result := StrToBoolDef(PostHTTPPageEx(MyClient, {url}), False);
// We use False as if the site is down, then it's better to assume it's not so they check
FreeHTTPClient(MyClient);
end;
And with that setup, feel free to run it and play around for a bit. Changing the '1' to '0' or '0.5' etc. should lead to CheckVersion returning False, so make sure you have a WriteLn set in an if else in Scar or use BoolToStr to change it from a boolean to a string. The simple use for this is that you can put the function into an if and if it returns false, then tell them to go to your website to make sure it's the latest version otherwise say it's up-to-date. When you're done playing, this tutorial will unfortunately have to end for now, so all I can do is wish you goodbye and don't have nightmares. Also, for a sneak preview of next time, we will be using and abusing the case equivalent in php to enable us to check multiple scripts versions with just 1 php file! And we will get one step closer as we throw in a few more Post variables and add basic security so people can't view your php page unless they access it via your script! On a very last note (yes I promise this time) I'll only be continuing this tutorial if there's some demand (2 or 3 people atleast would be nice :))
This tutorial will be broken into about 4 or 5 or 6 parts (not sure yet as I'm writing it a section at a time) and will help you understand how SRL Stats works and help you involve php and databases in your scripts to make them that bit more uber 1337 as well as setup your own basic SRL Stats to show the possibilites of Scar, php and databases. In this first part, I will be showing you how to setup a basic php script and getting it to return a value back to Scar and basic version checking to your PHP file so it can be useful to the common user. Also, mods, if you feel this should go in another section, then feel free to move it - I thought it should go here because it has very simple code, but the idea in principle is more advanced than a basic user, so :spongebob:
First of all, you must have webhosting of some kind. You can get free webhosting and if you're not sure where, then I don't have any direct links, but I can suggest something - *cough* google *cough* - and most free webhosting will also come with a database and a file uploader so you don't need a program like Microsoft FrontPage or Dreamweaver (ftw!) and can instead just write it in notepad and save it with .php on the end (make sure you choose 'All Files' in the dropdown in save/as otherwise it will save it as .php.txt). If you need more help with webhost's or uploading etc. feel free to PM me or post in this topic (though check the topic before posting or pm'ing as your qeustion may have already been answered!).
Now, onto the tutorial!
We will be starting out by making a Scar function that returns the contents of a webpage. Remember to replace all '{url}'s with the appropriate url to your php page. Now, most people will know about 'GetPage()', but we won't be using that for this tutorial as it doesn't allow us to output anything, so what we will be using instead is 'PostHTTPPageEx'. It is a lot more complex to set up, but it is worth it in the long run with what it allows us to do. If you look it up in the Scar library (F1), then you will find out it needs the following variables: Client - Integer and Url - string and also outputs a string. Well, what's Client? It's a variable that holds all the extra data to be sent to a webpage and needs to be set up before and cleared afterwards (well, it doesn't need to, but it should be) and for this tutorial, I will be using 'MyClient' simply because when I learnt about it, it seemed like an obvious choice. So to set it up we just assign our variable to 'InitializeHTTPClient(False, False);' The first False relates to handling Cookies and the second to handling Redirects. Unless you're an advanced php scripter, then you will probably have no idea how to use either, so it's better just to leave them to false for now. With that bit, we now have our first variable set up and the second one we can leave until the php file is up. So with that, we just have to clear the Client using 'FreeHTTPClient(MyClient);' replacing 'MyClient' with the variable you used for the client if it differs. With all that sorted, we just need to make it so that the result is assigned to PostHTTPPageEx so our function returns the "webpage" (more on that in a bit) and we're done! If you were following the scripting, you should get something like the following. If you're just reading through, make sure you go over the general layout a few times as it will be used repeatedly for the rest of the tutorial.
function ReturnPage: string;
var
MyClient: integer;
begin
MyClient := InitializeHTTPClient(False, False);
AddPostVariable(MyClient, 'pName', 'pValue'); // Ignore this for now, it only stops an error from happening
Result := PostHTTPPageEx(MyClient, {url});
FreeHTTPClient(MyClient);
end;
You can test the script by WriteLn'ing the function using 'http://google.com' as the url and you should get 'HTTP/1.0 501 Not Implemented' in the debug box (it sounds like an error, and it is, but it means that it's working). With that sorted, we just need to know how information is received by PostHTTPPageEx. Well, it takes in all of the source that is shown on the webpage (so if you went to view->source now, that's what would be returned by this page). So, we know how data is received, now we just need to know how to output code in php. Now, if you know basic php, then feel free to skip the next paragraph.
When writing a php file, you have to tell it when to start reading the code as php code with php tags. The open tag, which tells it to read as php code, is '<?php' and with the closing tag, which tells it stop reading the code as php, being '?>'. The second thing to know, is that every command has to be terminated with a semi-colon - ; - otherwise it will give you an error. The next thing to learn is how to output code. As php doesn't write out everything in it as code, it has to have a special command to tell it when to - just like WriteLn does - and that is 'echo'. It's very easy to remember 'echo' when you think of it as 'echo'ing what it is submitted to it. Unlike Scar though, most php commands (including echo) don't need parenthesis enclosed around it, so you can just put echo 'cheese'; to write out cheese and you can also do echo('cheese'); - neither is wrong, but practially all php scripters reserve parenthesis for mathematical uses. Also, you can use apostraphes (' ') or quote marks (" ") to mark strings, which makes things a lot easier with longer or more complex strings as you don't have to remember to double up your apostraphes if you use quote marks. Next, instead of using + to indicate when to join strings together, you use periods - . - which ties in nicely with my next point that php supports flexible variables. It means that you can assign a variable with a number in a string (like '2') and then add it to another number! It also means no more IntToStr's or StrToInt's or declarations (yes, no need to declare variables in a var section) and all you have to do is make sure you put a dollar sign ($) before variables (though always remember to double-check names)! For my last point for this bit, the assignment and comparatives are slightly in different in php. = is the assigner instead of := and .= adds onto a string, (so you can do string := 'rawr'; string .= '2'; and string will hold a value of 'rawr2') which can be very handy, though not so much in this tutorial for now.
Now with that bit of knowledge under your belt, we can make the absolute simplest way to use php usefully in your script, and that is a version checker that will also give you a little taste of php. The starting point of it will be the php open and close tags (<?php and ?>). After that, we will use a variable called $version (remember the $!) and assign it a value of 1 for this file for now. After that, we want to 'echo' the value of $version, which means that the source will have the value of $version, which is what PostHTTPPageEx will return to Result in our Scar function. So, you should have the following php file so far:
<?php
$version = 1;
echo $version;
?>
I know it doesn't look very classy or complex, but it is a start. You can test it now if you want by uploading it to your host (make sure it has a .php file extension) and fill in the url in your Scar function and you should see a popup asking for permission to access the file, then a '1' should appear in your debug box if you tell it it WriteLn the function (so 'WriteLn(ReturnPage);'). Well done, you have now made a simple function, but one that will grow in power as you learn more.
Now, I did promise you a version checker, and I am here to please you. What you could do is make the version checking bit in the Scar script, but where's the fun in that? So what I will be teaching you now is how to make an 'if' in php. It is more or less the same as in Scar, except with slight differences. It still has the basic syntax of 'if(Exp1 Comp Exp2)' (I'm sorry to say you MUST have parenthesis for if's check in php) which returns a true or false, depending on the expressions (Exp1 and Exp2) and the comparative (Comp). After that it differs slightly. Instead of having 'then' and 'begin', you just use an open curly brace - { - and you use a closing curly brace as the 'end;' - } with all code lines going in between them and you must use both ( { } ) regardless of length (so even with just 1 line commands, though with it being so short, it's hard to complain) . 'else' works pretty much the same - goes after the end (no more worrying about removing the semi-colon after the end!) and 'else if' works just like an else then an if (as you would assume). The only comparatives you need to know for now are: == which is equal to (as we can't use = which is the assigner), != which is not equal to for everything except numbers, <> which is not equal to for numbers and < or > which is the greater than or less than sign which works the same as in Scar.
So with that done, we just have to work out how to send information from our Scar script to our php file. The possible ways are using Get and Post. Post is a much more secure way that is often present in forms (such as a login form), while Get is actually visible and easily changable, but why use Get? Well, it means you can save a webpage in an almost exact format. Forums will often use it to store the topic or post, which means you can bookmark an exact page as the Get variable is stored along with it! For this, we will be using Post as the security will mean that outside users can't access the details and we already have POSTHTTPPageEx pretty much setup. The only thing to explain is how to add Post variables to a client. Well, we already have one setup! The 'AddPostVariable(MyClient, 'pName', 'pValue');' adds a Post variable to the client MyClient, with the variable being named pName and its value being pValue. So all we have to do is adjust it to our needs. As we're checking versions, SVersion sounds like a good name for it (with the 'S' referring to Script or Scar) and a value of '1' will do for now. So, with our variable set up, let's use it in our php script using our well known if else we just learnt! But wait, how do we access post variables, because they aren't sent as $SVersion, but instead as $_POST['SVersion']. Now this may confuse you, but php supports arrays with string indexes as well as numbers, while in scar you can only have arr[0], arr[1] etc. you can have arr[0], arr['donkey'] in php, so how cool is that? Now is the time to advance! So what we want to do is check to see if $_POST['SVersion'] is equal to $version and if it is, then we want to output 'true', otherwise we want to output 'false' - yes I am going to be changing our Scar function to output a boolean, so you better watch out! Now you should be able to code this with what you've learnt, but don't worry if you can't do it as it can be hard to pick up a new language, so that's why I'm here!
<?php
$version = 1;
if($_POST['SVersion'] == $version)
// Flexible variables means we don't have to convert the Post var!
// and yes, // = comments in php too!
{
echo 'true';
}
else
{
echo 'false';
}
?>
So, we have our php set up and all we need to do is convert our Scar to work with a boolean as well. I'll also be changing the name to 'CheckVersion' and make it output a boolean, so if you're coding along, be sure to do that quickly. Done? OK, next step is to use a valuable conversion function when using php called 'StrToBoolDef' which will convert the php files outputted code into a boolean and if it isn't a valid boolean, then it returns a default boolean, which gives us a nice output for our function. So, you should have a Scar function resembling this:
function CheckVersion: boolean;
var
MyClient: integer;
begin
MyClient := InitializeHTTPClient(False, False);
AddPostVariable(MyClient, 'SVersion', '1');
Result := StrToBoolDef(PostHTTPPageEx(MyClient, {url}), False);
// We use False as if the site is down, then it's better to assume it's not so they check
FreeHTTPClient(MyClient);
end;
And with that setup, feel free to run it and play around for a bit. Changing the '1' to '0' or '0.5' etc. should lead to CheckVersion returning False, so make sure you have a WriteLn set in an if else in Scar or use BoolToStr to change it from a boolean to a string. The simple use for this is that you can put the function into an if and if it returns false, then tell them to go to your website to make sure it's the latest version otherwise say it's up-to-date. When you're done playing, this tutorial will unfortunately have to end for now, so all I can do is wish you goodbye and don't have nightmares. Also, for a sneak preview of next time, we will be using and abusing the case equivalent in php to enable us to check multiple scripts versions with just 1 php file! And we will get one step closer as we throw in a few more Post variables and add basic security so people can't view your php page unless they access it via your script! On a very last note (yes I promise this time) I'll only be continuing this tutorial if there's some demand (2 or 3 people atleast would be nice :))