Location: PHPKode > scripts > PuszBaza > puszbaza/PB_1_2_help_en.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-2">
<TITLE>PuszBaza 1.2 help</TITLE>

<STYLE>
<!--
A        {color: #000082; text-decoration: none; font-family: Verdana; font-size: 11px; FONT-WEIGHT: bold;}
A:hover  {color: white; text-decoration: none; font-family: Verdana; font-size: 11px;}

BODY     {SCROLLBAR-FACE-COLOR: #395893; SCROLLBAR-ARROW-COLOR: white; SCROLLBAR-TRACK-COLOR: #2b3357;}
P        {TEXT-ALIGN: justify; COLOR: #000000; FONT-SIZE: 11px; FONT-FAMILY: Verdana; 
          MARGIN-LEFT: 3%; MARGIN-RIGHT: 4%; LINE-HEIGHT: 180%;}
SPAN     {FONT-SIZE: 11px; FONT-FAMILY: Verdana; COLOR: white; FONT-WEIGHT: bold; BACKGROUND: #395893;}
.uwaga   {BACKGROUND: red;}

H1       {FONT-FAMILY: Impact, Verdana, Arial; FONT-WEIGHT: bold; FONT-SIZE: 35pt; COLOR: #000082; MARGIN-LEFT: 3%;}
H2       {FONT-FAMILY: Verdana, Arial; FONT-WEIGHT: bold; FONT-SIZE: 15pt; COLOR: #000082; MARGIN-LEFT: 3%;}
H3       {FONT-FAMILY: Verdana, Arial; FONT-WEIGHT: bold; FONT-SIZE: 12pt; COLOR: #000082; MARGIN-LEFT: 3%;}

PRE      {MARGIN-LEFT: 6%; MARGIN-RIGHT: 3%; LINE-HEIGHT: 180%;}
HR       {COLOR: #395893; MARGIN-LEFT: 3%; MARGIN-RIGHT: 4%;}
TABLE    {BACKGROUND: white; MARGIN-LEFT: 3%; MARGIN-RIGHT: 3%; WIDTH: 93%;}
-->
</STYLE>
</HEAD>

<BODY BGCOLOR="#BCD0FE">
<H1>PuszBaza 1.2</H1>

<UL>
<LI><A HREF="#intro">Introduction</A>
<LI><A HREF="#install">Installation</A>
<LI><A HREF="#functions">Functions & variables</A>
<LI><A HREF="#displaying">Displaying results</A>
<LI><A HREF="#tips">Tips & tricks</A>
<LI><A HREF="#plans">Plans for the future</A>
</UL>

<HR>
<P>The author, Michael &#8222;Puszkin&#8221; Marszalik, grants you <B>PuszBaza</B> (pronounced 
push-b^s^ [where ^ stands for short <I>a</I> as in <I>much</I>]) as a freeware. You can copy and use
it for private or commercial websites, but you can't charge for PuszBaza. The author may not be held
responsible for any undesirable results of using the script and he can not guarantee that PuszBaza
would suit your particular needs: using PushBaza is entirely at your own risk. You have been warned
:-)<BR>
Do not hesitate to send questions & comments regarding the script to <A
HREF="mailto:hide@address.com">hide@address.com</A>, while comments about this doc to mr. <A
HREF="mailto:hide@address.com?Subject=Uwagi do dokumentacji PuszBazy">Przemyslaw Jackowski</A>. The latest 
version of PuszBaza can be found at <A HREF="http://www.puszkin.polbox.pl/">http://www.puszkin.polbox.pl/</A>. </P>
<HR>

<A NAME="intro"></A><H2>Introduction</H2>
<P>PuszBaza is a database script written solely in PHP4 to assist people without MySQL or PostgreSQL 
access writing their database applications like guestbook, phorum, poll etc. &#8211; or even more 
complex projects. PuszBaza uses text files (&#8222;flat files&#8221;) similar to csv (=&#8222;comma 
separated values&#8221;), ie. with the following structure: first line contains field names, 
separated with semicolons, while records are placed in consecutive lines, eg.: </P>

<PRE>
id;author;title;
1;Agatha Christie;Evil Under The Sun;
2;Arthur Conan Doyle;A Study in Scarlet;
3;Raymond Chandler;Farewell My Lovely;
</PRE>

<P>The only difference between PuszBaza's file format and csv is <B>last field in a record that 
shall be followed by semicolon</B>, ie. at the end of each line. For the sake of this document
data files will have <B>pbf</B> extension (=&#8222;PuszBaza format&#8221; ;-) while in fact it can
be any (eg. txt). </P>

<P>To make use of PuszBaza it is enough to write just one line of code: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
include "puszbaza.php";
?&gt;</PRE></TD></TR></TABLE>

<P><SPAN>&nbsp;HINT:&nbsp;</SPAN> For quick displaying of webpages using PuszBaza you may delete 
from <B>puszbaza.php</B> all the comments and functions of no use eg. <B>delete_pb</B> or 
<B>update_pb</B>. </P>

<P><SPAN>&nbsp;HINT:&nbsp;</SPAN> Database file (*.pbf, *.txt) should have write permissions granted 
for everyone; in other case <B>Permission denied</B> message is displayed and no operations
on the data is possible. You can use any ftp manager (like CuteFTP, LeechFTP etc.) to set 
(chmod) these permissions. </P>

<P><SPAN>&nbsp;ATTENTION:&nbsp;</SPAN> There is virtually no protection for the PuszBaza data files. 
Learning by anyone the name of the data file enables intruders unauthorised access. </P>

<HR>

<A NAME="install"></A><H2>Installation</H2>
<P>There is no need for any special installation &#8211; just copy file <B>puszbaza.php</B> to the
directory where other files of your project are kept, and that's all! </P>

<HR>

<A NAME="functions"></A><H2>Functions & variables</H2>
<UL>
<LI><A HREF="#connect">connect_pb</A>
<LI><A HREF="#select">select_pb</A>
<LI><A HREF="#count">count_pb</A>
<LI><A HREF="#insert">insert_pb</A>
<LI><A HREF="#update">update_pb</A>
<LI><A HREF="#delete">delete_pb</A>
</UL>

<HR>
<A NAME="connect"></A><H3>connect_pb</H3>

<P><SPAN>&nbsp;SYNTAX:&nbsp;</SPAN> connect_pb("filename"); </P>

<P><SPAN>&nbsp;DESCRIPTION:&nbsp;</SPAN> <BR> 
<B>filename</B> is data file name with any extension; fields should be separated with semicolons;
you can use path. </P>

<P><SPAN>&nbsp;PURPOSE:&nbsp;</SPAN> <B>connect_pb</B> connects to data file. </P>

<P><SPAN>&nbsp;EXAMPLE no. 1:&nbsp;</SPAN> For <B>my_data.pbf</B> connection would be following: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$conn = connect_pb("my_data.pbf");
?&gt;</PRE></TD></TR></TABLE>

<P>Data file may be stored in other directory then <B>puszbaza.php</B>: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$conn = connect_pb("my_databases/this_base/my_data.pbf");
?&gt;</PRE></TD></TR></TABLE>

<P>You can use variable as well: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$filename = "my_databases/this_base/my_data.pbf";
$conn = connect_pb($filename);
?&gt;</PRE></TD></TR></TABLE>

<P><B>connect_pb</B> returns variable (array with all values), on which you can use <A 
HREF="#select">select_pb</A>. After single call to <B>connect_pb</B> you can use <B>select_pb</B> as 
many times as you need, but if in the meantime data file was altered (eg. after using <A 
HREF="#insert">insert_pb</A>, you should re-use <B>connect_pb</B>. </P>

<HR>
<A NAME="select"></A><H3>select_pb</H3>

<P><SPAN>&nbsp;SYNTAX:&nbsp;</SPAN> select_pb($conn,'field','condition'[,'field_to_sort_by'][,'sorting_order']); </P>

<P><SPAN>&nbsp;DESCRIPTION:&nbsp;</SPAN><BR>
<B>$conn</B> &#8211; variable returned by <B>connect_pb</B> <BR>
<B>field</B> &#8211; name of the field, to which <B>condition</B> applies<BR>
<B>condition</B> &#8211; PHP-like condition (eg. np. <B>==</B> means &#8222;equals to&#8221;, 
<B>!=</B> means &#8222;is not equal to &#8221; etc.); instead of column name put <B>x</B> here <BR>
<B>field_to_sort_by</B> &#8211; name of the filed, according to which data are to be sorted (this entry is optional) <BR>
<B>sorting_order</B> &#8211; it may be <B>ASC</B> (ascending) or <B>DESC</B> (descending) (this entry 
is optional also and defaults to <B>ASC</B>) </P>

<P><SPAN>&nbsp;PURPOSE:&nbsp;</SPAN> <B>select_pb</B> makes it possible to display only chosen 
(according to specified condition[s]) data from a file and sort them in desired order. </P>

<P><SPAN>&nbsp;EXAMPLE no. 2:&nbsp;</SPAN> find all the records for which value of <B>id</B> is
bigger then 2 and sort them ascending according to <B>id</B> field:</P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$conn = connect_pb("my_data.pbf");
$result = select_pb($conn,"id","x > 2",'id',"ASC");
?&gt;</PRE></TD></TR></TABLE>

<P><SPAN>&nbsp;ATTENTION:&nbsp;</SPAN> You can use any function that returns <B>true</B> or 
<B>false</B> as a <B>condition</B>, eg. you can use <B>ereg('2',x)</B> (which behaves in similar
manner as <B>like</B> in SQL) &#8211; you should remember to use quotation marks. </P>

<P><SPAN>&nbsp;EXAMPLE no. 3:&nbsp;</SPAN> find all the records, for which <B>title</B> field
contains phrase <B>th</B> and sort them ascending according to <B>id</B> field: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$result = select_pb($conn,"title","ereg('th',x)",'id',"ASC");
?&gt;</PRE></TD></TR></TABLE>

<P><SPAN>&nbsp;EXAMPLE no. 4:&nbsp;</SPAN> Is it possible to use more than one condition to select 
records? Yes, it is, but in that case conjunction of conditions should be used, ie. only AND should 
be used (using OR or brackets will result in error message). In all conditions <B>x</B> should be 
used; PuszBaza will take care about appropriate field names; all you have to remember is to use the 
same number of fields separated with ANDs as the number of conditions, also separated with ANDs. 
Attention: 1) AND must be written in uppercase; 2) name of the field, on which <B>select_pb</B> results 
are to be sorted should be specified. In the example below all the records, for which values of 
<B>id</B> field is bigger or equal to 1 and smaller than 3, while value of <B>date</B> field is 
smaller than March, 12th 2001 will be selected and sorted according to values of <B>id</B> field: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$result = select_pb ($conn,"id AND id AND date","x >= 1 AND x < 3 AND mktime(x) < mktime('12-3-2001')","id") 
?&gt;</PRE></TD></TR></TABLE>

<HR>

<A NAME="count"></A><H3>count_pb</H3>

<P><SPAN>&nbsp;SYNTAX:&nbsp;</SPAN> count_pb($result); </P>

<P><SPAN>&nbsp;DESCRIPTION:&nbsp;</SPAN><BR>
<B>$result</B> &#8211; variable returned by <A HREF="#select">select_pb</A> </P>

<P><SPAN>&nbsp;PURPOSE:&nbsp;</SPAN> <B>count_pb</B> returns the number of records (ie. lines of
data file), which meet condition specified in <A HREF="#select">select_pb</A>.

<P><SPAN>&nbsp;EXAMPLE no. 5:&nbsp;</SPAN> display number of records, for which value of <B>id</B> is
bigger than 2: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$conn = connect_pb("my_data.pbf");
$result = select_pb($conn,"id","x > 2",'id',"ASC");
$number = count_pb($result);
?&gt;</PRE></TD></TR></TABLE>

<HR>
<A NAME="insert"></A><H3>insert_pb</H3>

<P><SPAN>&nbsp;SYNTAX:&nbsp;</SPAN> insert_pb("filename","record"); </P>

<P><SPAN>&nbsp;DESCRIPTION:&nbsp;</SPAN><BR>
<B>filename</B> &#8211; data file name <BR>
<B>record</B> &#8211; full record, ie. with all fields declared in the first line of <B>filename</B> </P>

<P><SPAN>&nbsp;PURPOSE:&nbsp;</SPAN> <B>insert_pb</B> adds new record to the data file. </P>

<P><SPAN>&nbsp;EXAMPLE no. 6:&nbsp;</SPAN> </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
insert_pb("my_data.pbf","4;Ross McDonald;The Galton Case;");
?&gt;</PRE></TD></TR></TABLE>

<P><SPAN>&nbsp;ATTENTION:&nbsp;</SPAN> You should remember not to use any additional semicolons 
in <B>record</B> other than field separators, or there will be some more fields :-) To ensure 
there are no such semicolons <B>ereg_replace()</B> can be used: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$value1 = ereg_replace(";","",$value1);
$value2 = ereg_replace(";","",$value2);
$value3 = ereg_replace(";","",$value3);
insert_pb("my_data.pbf","$value1;$value2;$value3;")
?&gt;</PRE></TD></TR></TABLE>

<P>In order to use semicolons, which are used quite often in guestbooks entries or phorums, it is 
enough to replace them with any other string before <B>insert_pb</B>, eg.: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$value = ereg_replace(";","##semicolon##",$value);
?&gt;</PRE></TD></TR></TABLE>

<P>and after <B>select_pb</B> return to the original version: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
$value = ereg_replace("##semicolon##",";",$value);
?&gt;</PRE></TD></TR></TABLE>

<HR>
<A NAME="update"></A><H3>update_pb</H3>

<P><SPAN>&nbsp;SYNTAX:&nbsp;</SPAN> update_pb("filename","field","condition", "key","value"); </P>

<P><SPAN>&nbsp;DESCRIPTION:&nbsp;</SPAN><BR>
<B>filename</B> &#8211; data file name <BR>
<B>field</B> &#8211; field name, for which <B>condition</B> is set <BR>
<B>condition</B> &#8211; PHP-like condition (as in <A HREF="#select">select_pb</A>)<BR>
<B>key</B> &#8211; field of which values will be changed <BR>
<B>value</B> &#8211; new value for <B>key</B> field </P>

<P><SPAN>&nbsp;PURPOSE:&nbsp;</SPAN> With <B>update_pb</B> you can change values in one or more
records. </P>

<P><SPAN>&nbsp;EXAMPLE no. 7:&nbsp;</SPAN> To change <B>author</B> field value for all the records 
from the second on to &#8222;Raymond Chandler&#8221; you should use: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
update_pb("my_data.pbf","id","x > 2","author","Raymond Chandler");
?&gt;</PRE></TD></TR></TABLE>

<HR>
<A NAME="delete"></A><H3>delete_pb</H3>

<P><SPAN>&nbsp;SYNTAX:&nbsp;</SPAN> delete_pb("filename","field","condition"); </P>

<P><SPAN>&nbsp;DESCRIPTION:&nbsp;</SPAN><BR>
<B>filename</B> &#8211; data file name <BR>
<B>field</B> &#8211; name of the field, for which <B>condition</B> is set <BR>
<B>condition</B> &#8211; PHP condition (like in <A HREF="#select">select_pb</A>) </P>

<P><SPAN>&nbsp;PURPOSE:&nbsp;</SPAN> <B>delete_pb</B> deletes any record, for which <B>condition</B>
is conformed. </P>

<P><SPAN>&nbsp;EXAMPLE no. 8:&nbsp;</SPAN> delete all the records for which field <B>author</B> has
value &#8222;Raymond Chandler&#8221;: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
delete_pb("my_data.pbf","author","x == 'Raymond Chandler'");
?&gt;</PRE></TD></TR></TABLE>

<HR>

<A NAME="displaying"></A><H2>Displaying results</H2>

<P><SPAN>&nbsp;EXAMPLE no. 9:&nbsp;</SPAN> to display all records can be used: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
include "puszbaza.php";
$conn = connect_pb("my_data.pbf");
$result = select_pb($conn,"id","x > -1",'id',"ASC");
$number = count_pb($result);

for($i=0; $i < $number; $i++)
 {
 $id = $result["id"][$i];
 $author = $result["author"][$i];
 $title = $result["title"][$i];
 echo "$id) $author: &lt;B>$title&lt;/B> &lt;BR>";
 }
?&gt;</PRE></TD></TR></TABLE>

<P>The result will be following: </P>
<TABLE><TR><TD>
1) Agatha Christie: <B>Evil Under The Sun</B><BR>
2) Arthur Conan Doyle: <B>A Study in Scarlet</B><BR>
3) Raymond Chandler: <B>Farewell My Lovely</B>
</TD></TR></TABLE>

<P>Condition "x > -1" was made on purpose: this way all the records will be displayed, even this 
with <B>id</B> of 0. </P>

<P><SPAN>&nbsp;HINT:&nbsp;</SPAN> To display <B>all</B> records of the data file, where there is
no <B>id</B> field, you should treat result of <B>connect_pb</B> as if it was result of <B>select_pb</B>: </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
include "puszbaza.php";
$conn = connect_pb("my_data.pbf");
$count = count_pb($conn);

for($i=0; $i < $number; $i++)
 {
 $id = $conn["id"][$i];
 $author = $conn["author"][$i];
 $title = $conn["title"][$i];
 echo "$id) $author: &lt;B>$title&lt;/B> &lt;BR>";
 }
?&gt;</PRE></TD></TR></TABLE>

<HR>

<A NAME="tips"></A><H2>Tips & tricks</H2>

<H3>max, min, sum</H3>

<P>This functions can be used for the purpose of determining the field with: the biggest value, 
the smallest value and sum of fields' values. </P>

<P><SPAN>&nbsp;EXAMPLE no. 10:&nbsp;</SPAN> </P>

<TABLE><TR><TD><PRE>
&lt;?PHP
include "puszbaza.php";
$conn = connect_pb("my_data.pbf");
$result = select_pb($conn,"id","x > -1",'id',"ASC");

if ($result != 0) $id_max = max($result["id"]);
if ($result != 0) $id_min = min($result["id"]);
if ($result != 0) $id_sum = array_sum($result["id"]);
?&gt;</PRE></TD></TR></TABLE>

<H3>$data</H3>

<P>How can you save information about the date, so as you could easily sort entries (ASC or DESC) 
according to it? One line would be enough: </P>

<TABLE>
<TR><TD><PRE>&lt;?PHP
$data = date("ymdHi");
?&gt;</PRE></TD></TR>
</TABLE>

<P>This way in <B>$data</B> variable the date was written in <B>yymmddhhmm</B> format, ie.
eg. 0205122045 (= <B>12.05.02, 20:45</B>). Since the year was written in the first place, 
then the month, the day etc., you can sort dates comparing them as if they were just numbers: 0205122045 
is bigger than eg. 0203251212 (=25.03.02, 12:12), which means that the former mentioned date comes
later than the latter one. <BR>
Beware: this trick works well only for years from 2000 on; to compare earlier dates four digits to write 
a year shall be used, ie. </P>

<TABLE>
<TR>
<TD><PRE>&lt;?PHP
$data = date("YmdHi");
?&gt;</PRE></TD></TR>
</TABLE>

<P>How can this date be modified to &#8222;ordinary&#8221; one? Eg. as follows: </P>

<TABLE>
<TR>
<TD><PRE>&lt;?PHP
function data_norm($var)
{
$var = $var[4].$var[5].'.'.$var[2].$var[3].'.'.$var[0].$var[1].', '.$var[6].$var[7].':'.$var[8].$var[9];
return $var;
}
?&gt;</PRE></TD></TR>
</TABLE>

<P>You may need to modify the code above to display the date just in the form that is used in your 
country. </P>

<P><SPAN>&nbsp;EXAMPLE no. 11:&nbsp;</SPAN></P>

<TABLE>
<TR>
<TD><PRE>&lt;?PHP
$var = '0203251212';
echo data_norm($var);
?&gt;</PRE></TD></TR>
</TABLE>

<P>...will bring as a result: </P>

<TABLE>
<TR>
<TD><PRE>25.03.02, 12:12</PRE></TD></TR>
</TABLE>

<HR>

<A NAME="plans"></A><H2>Plans for the future</H2>

<P>If you have a good idea for a function that might be added to PuszBaza, <A 
HREF="mailto:hide@address.com">email me</A>! </P>

</BODY>
</HTML>
Return current item: PuszBaza