 |
 |
 |
 |
|
|
Date: 05/07/00
- Next message: ssilk: "[phplib-dev] cvs commit"
- Previous message: athompso: "[phplib-dev] cvs commit"
- Next in thread: ssilk: "[phplib-dev] cvs commit"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
From: ssilk
Date: Mon May 8 03:42:14 2000
Modified files:
php-lib/doc/sgml/04-query.sgml
Log message:
Completed the documentation. I look at my clock and it says "GO TO BED!".
So there are some errors left in this SGML. I havn't found a documentation
about docbook and I don't feel like doing so. Perhaps someone who does
those things every day could fix it, please?
Index: php-lib/doc/sgml/04-query.sgml
diff -u php-lib/doc/sgml/04-query.sgml:1.3 php-lib/doc/sgml/04-query.sgml:1.4
--- php-lib/doc/sgml/04-query.sgml:1.3 Sun May 7 06:06:04 2000
+++ php-lib/doc/sgml/04-query.sgml Mon May 8 03:42:12 2000
@@ -1,19 +1,21 @@
-<!-- $Id: 04-query.sgml,v 1.3 2000/05/07 04:06:04 athompso Exp $ -->
+<!-- $Id: 04-query.sgml,v 1.4 2000/05/08 01:42:12 ssilk Exp $ -->
<sect1>Query
<p>
-The Query-class is an enhancement to the DB_Sql-class.
+The Query-class is an enhancement to the DB_Sql-class.
+It is a type of helper-class to help you in creating Queries to a
+SQL-Database.
+Cause it uses very common sql-queries, we hope it could support every
+sql-database.
-If you know Perl's db-interface modules you perhaps have an idea, what it
-is.
-
-Cause it uses very common sql-queries I hope it could support every
-sql-database. The man compatibility issues are the function metadata()
+The main compatibility issues are the function metadata()
in DB_Sql. Currently only db_mysql.inc and db_oracle.inc have this
extended version of metadata(). But it is easy for every programmer
to extend this function.
+<sect2>Installation and use
+<p>
<em/It always needs the class DB_Sql!/
Query is fully upward compatible with DB_Sql. To use Query, you only have
@@ -29,10 +31,10 @@
$db = new hugobla;
</code></tscreen>
-Just edit the file prepend.php3 and add this line:
+Just edit the file prepend.php3 and add this line (if it isn't in the file):
<tscreen><code>
-require($_PHPLIB["libdir"] . "user.inc");
+require($_PHPLIB["libdir"] . "query_sql.inc");
</code></tscreen>
and in the file local.inc replace "DB_Sql" with "Query".
@@ -40,90 +42,282 @@
That's all...
+<sect2>What is it? How can I use it?
+<p>
+
Query just provides a number of new functions.
-The Query-class is inteded to help you with creating selects, inserts,
+The Query-class is inteded to help you with creating upward-compatible
+selects, inserts,
updates, where-clauses etc. Not just <em/simple/ selects, but longer ones. It
-is indeed a great help for tables with more than 10-20 columns. But it can
-also be used for simple and small selects. The inbuilt checks help you
+is indeed a great help for tables with more than 10-20 columns.
+
+But it can
+also be used for simple and small selects - especially, when you know that the
+definition of this class will change in the future.
+
+The inbuilt checks help you
programming saver (and in this way faster). The last purpose is the handling
of the vars from a form or into a form.
-Here are some examples, it will show you some expample of how easy
+Here are examples (planned), it will show you some expample of how easy
<tt/Query/ can be used:
+The first example show a very <em/simple/ and <em/generic/ editor for the
+table "auth-user":
+
<tscreen><code>
-file: insert.php3
------------------
-<?
-## gets data from my form and inserts it into db
-
-require("prepend.inc"); ## here the classes are loaded and configured
-$db = new hugobla;
-$db->query($db->insert_plain_Clause("mytable",$db->capture_vars("mytable"),ARRAY
-()));
-echo "Values inserted";
+file: user-interface.php
+------------------------
+<?php
+
+function check_mypasswords($p1,$p2) {
+ if (!empty($p1) && !empty($p2)) {
+ if ($p1 != $p2) {
+ return("Passwords are not matching!");
+ }
+ }
+ return(false); # ok
+}
+
+function check_userintable($name) {
+GLOBAL $db,$tabname;
+ if ($db->exists($tabname,ARRAY(p_username=>$name)))
+ return(true); # ok
+ else
+ return(false);
+}
+
+# we will not explain it much more, please
+# be free to "play" with this program
+
+require("db/mysql/db_sql.inc");
+require("query_sql.inc");
+
+class Query_Example extends Query {
+ var $Host = "localhost";
+ var $Database = "test";
+# var $Q_Debug=true; # uncomment for Debug-info
+}
+$tabname="auth_user";
+
+$db = new Query_Example;
+
+# collect formvalues from the form sent to this file from the call before
+# capure_vars() looks at the table auth_user and then it tries to
+# get all $GLOBALS with the name of the rows in your table and make
+# it to an associative array
+$fv = $db->capture_vars($tabname);
+
+
+switch ($action) :
+case 'insertnew':
+ ## look if input is valid
+ if (empty($p_password)) {
+ $Error="Password is empty!";
+ break;
+ } elseif (empty($p_username)) {
+ $Error="Username is empty!";
+ break;
+ } elseif (check_userintable($p_username)) {
+ $Error="User already exists, please choose another name!";
+ break;
+ }
+ if (!$Error = check_mypasswords($p_password,$p_password2)) {
+ ## calculate md5-string
+ $md5=Time();
+ for (reset($fv); list($key,$val)=each($fv);) {
+ $md5.=$key.$val; # sumarize string
+ }
+ $fv[p_user_id] = md5($md5);
+ $query=$db->Insert_Clause($tabname,$fv);
+ }
+ break;
+
+case 'update':
+ if (empty($p_username)) {
+ $Error="Username is empty!";
+ break;
+ } elseif (!check_userintable($p_username)) {
+ $Error="User doesn't exists, please choose an existing name!";
+ break;
+ }
+ if (!$Error = check_mypasswords($p_password,$p_password2) ) {
+ $query=$db->update_Clause($tabname,$fv);
+ }
+ break;
+
+case 'delete':
+ if (!check_userintable($p_username)) {
+ $Error="User doesn't exists, please choose an existing name!";
+ break;
+ }
+ if (!$sure) {
+ $Head="Are you really sure?
+<a href=\"$PHP_SELF?p_user_id=$p_user_id&sure=yes\">Yes</a>";
+ } else {
+ $query=$db->delete_Clause($tabname,$fv);
+ }
+endswitch;
+
+# execute query (if there is any)
+if (!empty($query)) {
+ $db->query($query);
+ switch (substr($query,0,1)) :
+ case 'I':
+ $Head="<big>New User '$p_username' inserted.</big><br>$query";
+ break;
+ case 'U':
+ $Head="<big>User '$p_username' updated.</big><br>$query";
+ break;
+ case 'D':
+ $Head="<big>$query<br>User '$p_username' deleted!</big><br>$query";
+ endswitch;
+}
+
+##################
+# begin of output
?>
+<html><body>
+<?php
-file: insert2.php3
--------------------
-<?
-## gets data from my form and inserts it into db with a new INDEX
-## myindex is defined as INT AUTO_INCREMENT PRIMARY KEY
-## (this is mysql, in oracle you have to define a trigger to do this)
-## mytime is defined as DATETIME (DATE in oracle)
-
-require("prepend.inc"); ## here the classes are loaded and configured
-$db = new hugobla;
-$mytime="SYSDATE()";
-$db->query($db->insert_plain_Clause("mytable",$db->capture_vars("mytable"),
- ARRAY(myindex=>'NULL',mytime=>'func')));
-echo "Values inserted: "$db->last_insert_id();
+if (!empty($Error)) {
+ echo "
+<table width=100% bgcolor=\"#EEAAAA\"><tr align=\"center\"><td>
+<div align=\"left\">ERROR:</div>
+<big><big>$Error<br><br></td></tr></table>
+";
+}
+if (!empty($Head)) {
+ echo "
+<br><big>$Head</big><br>
+";
+}
+
+# now generate the form
+# first we get the data for the form - if we have some
+
+if ($where = $db->unique_where_Clause($tabname,$fv)) {
+ $db->query("SELECT * FROM $tabname $where");
+ # this is the opposite of capture_vars(): It takes the
+ # associative Array $db->Record and assigns them to the global scope
+ $db->dispose_next_record();
+}
?>
+<p>
+<form action="<?php echo $PHP_SELF; ?>">
+<input type="hidden" name="p_user_id" value="<?php echo $p_user_id ?>">
+<input type="hidden" name="p_wenc" value="">
+
+<small>Username</small><br>
+<input name="p_username" value="<?php echo HTMLSpecialChars($p_username) ?>"><br>
+
+<small>Password</small><br>
+<input type="password" name="p_password" value="<?php echo
+HTMLSpecialChars($p_password) ?>"><br>
+<small>Repeat password</small><br>
+<input type="password" name="p_password2" value="<?php
+echo HTMLSpecialChars($p_password) ?>"><br>
+
+<small>Permission</small><br>
+<input name="p_perms" value="<?php echo HTMLSpecialChars($p_perms) ?>"><br>
+
+<input type="submit" name="action" value="insertnew">
+<input type="submit" name="action" value="update">
+<input type="submit" name="action" value="delete">
+</form>
+
+</html>
+</code></tscreen>
+
+This example is perhaps a little bit big. But it shows you many uses of Query,
+and how easy it can be used. :-)
+
+<sect2>Features
+<p>
+Query encapsulates the variable-types of the rows in your table in a way,
+that you never have to care, if a field is a string or a number. It
+automatically converts the values to the right form. But you also can make
+many exceptions. The values are automatically converted into the right form. The type
+of the vars are read from the table. <tt/String/-values are encapsulated with '
+(configurable) and will be escaped correctly, <tt/int/- and <tt/real/-values
+are casted. The strings can be automatically concatenated if needed. It can
+handle "NULL"-values, function-statements or any other values for insertion.
+
+Query has also the advancement, that changes to your tables (with ALTER
+TABLE for example) will not bother you too much. This makes it possible to
+use ALTER TABLE-commands without changing any line of your program! Also
+changing a field in a table from NUMBER to VARCHAR(10) is fully encapsulated
+with this class. For example if you change an integer-field to a
+string-field withing mySQL will make you by normal change all your Queries
+that they add a '-char before and after the value. Or the more often case,
+that you add a field in your table is handled without any changes in your
+program! Changes to your tables of your application will happen <em/much
+more often/ as changes of the underlaying DBMS. Query will make you very
+compatible with such changes. Most changes of the table layout can just be
+ignored into your application-code. This is quite important for big projects
+with much code. Changes in your data-modell will have nearly no bad
+side-effects.
+
+Query will convert every string-data through <tt/AddSlashes()/ by itself.
+This makes you free from using "magic_quotes_gpc", which is for
+bigger projects a very bad idea to use, cause you can have very much hassles
+with it. (The PHPLIB-core libraries itself dosn't need to have put on
+"magic_quotes_gpc").
+
+Query can also handle strings which are too long for your table by cutting
+them automatically to the maximum length (emulates the same automatism as mySQL
+uses).
+
+Query can handle also the case, that Oracle is not able to store the value
+NULL for empty string-fields.
+Empty string fields in Oracle are always NULL but aren't handled correctly
+within Oracle. You can see this behavior if you make the following
+SQL-statements withing sqlplus or worksheet:
+<tscreen><code>
+create table test (s varchar(20),d int);
+insert into test values ('',0);
+select * from test where s='' and d=0;
+</code></tscreen>
+<em/EVERY/ database I know get's out one line. But not Oracle. To find your
+data, you have to say
+<tscreen><code>
+select * from test where s is null and d=0;
</code></tscreen>
+This is a very dangerous thing, cause NULL is in PHP quite different to ''.
+Query tries to go arround this limitation in a way that you can call it
+better than nothing.
-This example is nice, cause you see how easy it can be used. :-)
+Query includes a patch that will create queries for SAP R3. SAP
+R3 handles NULL - or empty strings always as a single space. Some said, that
+there are some other Programs, that will also handle empty strings with this
+convention. Query will make this conversions for you.
-The best thing is, that you don't have to care, if a field is a string or a
-number. The values are automatically converted into the right form. The type
-of the vars are read from the table. Stringvalues are encapsulated with '
-(configurable) and will be escaped correctly, int- and real-values are
-casted, the strings can be automatically concatenated if needed. It can
-handle "NULL"-values, function-statements or other values for insertion.
-
-The last version includes a patch that will create queries for SAP R3. SAP
-R3 handles NULL- or empty strings always as a single space. Query will
-make this conversions for you.
-
-You will make less errors. <tt/Query/ is provided with a very fine
-debuging-mode.
-
-mySQL and most other DB's accept a short form of insert-clause like
-<tt/INSERT INTO bla VALUES (...)/. The Query-class will always make the
-longer form like <tt/INSERT INTO BLA (...) VALUES (...)/. This makes it
-possible to use ALTER TABLE-commands without changing any line of your
-program! Also changing a field in a table from NUMBER to VARCHAR(10) is
-fully encapsulated with this class.
-
-The class supports currently only mySQL and Oracle. I think the most
-differences between the DBs are encapsulated enough in the db_*-files, so it
-is possible to handle the remaining small differences inside this class
-(this affects mainly the function <tt/sql2phptype()/ ) and it could be
-easiely extended (asuming, that the <tt/metadata()/-function of the
-db_*-file works correct). In this case it is important, that the
-$type-variable in the db_*.inc-class is correctly set.
+The result of all this afford: You will make less errors.
<sect2> History and Philosophy of Query
<p>
+Query was born in Autumn 1998 by Alexander Aulbach (ssilk <email protected>) and is
+till now more or less made by myself for my own issues.
+
+It helped me a lot with my work and helped me at least one time to safe my
+neck from being hung. For example the patches for SAP R3 and Oracle was such
+a "being-hung-safer". The patches took aproximatly half a day (with testing
+etc). After doing the work I calculated the time for the case, that I used
+the "normal" way of creating queries without Query-class. I calculated about
+5 days, which is 10 times longer, cause the dependencies was inside nearly
+every Query and there where hundrets used in the application.
+
Query-class is not complete now. But it will never be complete. It just
provides the programmer with some functions, which will create strings or
part of strings, that could be used for generating a query in sql. This also
-declares the name of the file (<tt/query_sql.inc/), which must be included.
-Sorry for this name - <tt/sql_query.inc/ is in my eyes not even better.
+declares the name of the file (<tt/query_sql.inc/).
+
+Sorry for this name - <tt/sql_query.inc/ is in my eyes not even better. :-)
The idea of this class and also the name is based on a study-work
in November 1997 and there it was just a function-library for PHP/FI (PHP2).
@@ -140,9 +334,12 @@
functions, and we came to the conclusion, that we are using nearly the same
idea in creating the query-string. So I made a complete rewrite of this
first attempt and here it is.
+
+In Autumn/Winter 1999 I included some functions from Carmelo Guarneri and
+his class db_usql.
-<tt/Query/ is in my opinion stable (July '99) if you use it in a way I have
-tested it. The problem with testing this class is, that I can only test it
+<tt/Query/ is in my opinion beta (May 2000).
+The problem with testing this class is, that I can only test it
with my current work, so I have not much time to test it. :-) And perhaps
with some other dialects of SQL it will not work. But if you use this class
you will save many time in searching for errors. But it has it's overhead!
@@ -160,181 +357,1206 @@
with altering tables. Changes in your programm are done very easy, the order
of the values dosn't matter any more.
+The most disadvantage of Query is, that it is slower, than generating the
+queries "by hand". But on the other hand it is fast, cause you
+don't have to care about anything.
+
+
+
+
+
+<sect2> Some general notes
+
+
+
+<p>
+<descrip>
+<tag>Some things you could fall over very hard if you don't know</tag>
+Currently we cannot guarantee, that the result of a former query()-call is
+not overwritten. That means, that this for example dosn't work:
+<tscreen><code>
+ $db->query("select * from bla");
+ while ($db->next_record()) {
+ $iu=$db->iu_clause("blubb",$db->Record);
+ }
+</code></tscreen>
+This is cause iu_clause uses query() for itself, because
+currently Query-class cannot instanciate itself. In practice this is no
+problem at all, cause by normal you need for the above constructs always two
+instantiations of the class.
+
+
+
+<tag>General parameter settings</tag>
+
+Most of the *_Clause-functions do have those 3 params:
+
+<tt/function BLA_Clause($table,$fields,$special,.....)/
+
+<bf/$table/ is the name of the table in your DB you want to create a clause for.
+Query itself can currently only create queries for one table at a time.
+JOINS and other more or less complicated things are not supported by now.
+
+<bf/$fields/ is an associative array like
+<tscreen><code>
+ $fields=ARRAY (
+ first_name=>'Alexander',
+ last_name =>'Aulbach',
+ email =>'ssilk <email protected>',
+ bla =>'NULL');
+</code></tscreen>
+
+<bf/$special/ is also an associative array of nearly the same type. The only
+difference is that there are currently only 7 known values:
+NULL, func, string, double, int and a not existing (unset) value.
+
+<tscreen><code>
+ $special=ARRAY (
+ first_name=>'NULL',
+ last_name =>'func',
+ email =>'int');
+</code></tscreen>
+
+
+
+<tag>Exception for $fields</tag>
+
+If the field "bla" is defined as an integer a
+resulting insert-query will look like this:
+<code>
+ INSERT INTO bla (first_name,last_name,email,bla) VALUES
+ ('Alexander','Aulbach','ssilk <email protected>',NULL)
+</code>
+
+but if it is an CHAR-type it will look like
+<code>
+ INSERT INTO bla (first_name,last_name,email,bla) VALUES
+ ('Alexander','Aulbach','ssilk <email protected>','NULL')
+</code>
+
+This is because we assume, that the string "NULL" could be
+interpreted in the case of an underlaying integer- or real-value as NULL, in
+the case of a <em/string/ as 'NULL'.
+
+
+<tag>The $special-array</tag>
+
+Cause in this situation we can never fill up a char-field with the value
+NULL, we have invented the $special-parameter.
+The $special array gives you also some more control about
+other things. Seting <tt/$special=ARRAY(bla => 'NULL')/
+will force bla the value
+NULL, not the string 'NULL'.
+
+This depends every function which use the convert()-function in any way.
+In update-clauses for example, setting $special to 'NULL' will force an
+update for this field to the value NULL, instead of leaving it untouched
+if you don't set the field.
+
+[We are thinking about a value 'INVISIBLE' for the special array to make
+make this more clean]
+
+You can also force a value to be taken unchanged, no matter if it is a string
+or integer or whatever. For example:
+<tscreen><code>
+ $fields=ARRAY(bla=>'SYSDATE()',blubb=>'hugobla');
+ $special=ARRAY(bla=>'func');
+ echo $db->insert_plain_clause("test",$fields,$special);
+outputs
+ INSERT INTO test (bla,blubb) VALUES (SYSDATE(),'hugobla')
+</code></tscreen>
+Any other value than "NULL" or "function" must be a data-type. Query knows
+currently 3 types which are corresponding with the basic scalar types of PHP,
+namely: "string", "int" and "double". Setting the special-array
+to those values means to force the conversion to this data-type (if this
+has sense is another question :-).
+
+
+<tag>Difference between unset values and setting a value to NULL</tag>
+
+The insert-, update- and other depending functions do not handle unset
+field-values as the value NULL! They just do not make use of
+any of the unset values!
+
+If you want to use even unset values, you have to use the
+*_plain_*-functions. But their default is to set the values to 0 or ''.
+Please refer to the function themselfes about how they handle
+NULL-values.
+
+
+<tag>WHERE-parameter handling</tag>
+
+Some functions need an optional $where-parameter.
+The $where parameter for EVERY function call needs not to have an including
+"WHERE", you can just begin with "a=1 and b='x' ...". The "WHERE" is
+inserted automatically.
+
+
+<tag>Other Parameters</tag>
+
+With version 7.2 of PHPLIB, the $params-parameter was for most functions
+formerly the so called $check-parameter. To be upward compatible and for
+more comfort we made this agreement:
+
+If $params is a string, this means, that it is the $check-value.
+
+If it is an array you need to make it associative, e.g.:
+$params=ARRAY(check=>'weak',forceinsert=>true)
+
+
+<tag>Special or WHERE?</tag>
+
+Some functions allow to give over either a parameter $special or $where
+($special_or_where) and vice versa.
+
+This is, cause it is not comfortable to write function-calls like this:
+<tscreen><code>
+ $o=$db->update_Clause("bla",$fields,"","WHERE hugo=1");
+</code></tscreen>
+it's better to write
+<tscreen><code>
+ $o=$db->update_Clause("bla",$fields,"WHERE hugo=1");
+</code></tscreen>
+
+At this point you must know, that the parameter $special is always an array
+and the parameter $where is in this case always a string. With this
+knowledge Query can decide, wether the parameter at this place is
+$special or $where.
+
+
+<tag>WHERE as string or array</tag>
+
+The parameter $where_or_wfields can be given either as normal string
+(where-clause) or as an associative array. If it is an associative array, we
+assume, that the table you want to access has at least one unique identifier
+and we generate an where-clause out of it, that uses only those unique id's.
+
+
+<tag>You won't get happy with class Query?</tag>
+If you don't read the points above, this is true. Query is not thought for
+the one-night-programmer. It's written for programmers, which must do the
+same over and over again and need as much abrevations as possible.
+
+</descrip>
+<p>
+
+
+
+
<sect2> Instance variables
<p>
Cause <tt/Query/ is a subclass of DB_Sql it uses all the instance variables,
-which DB_Sql uses. I wont declare here again, see DB_Sql for more
-information.
+which DB_Sql uses. I wont declare this here again!
+See DB_Sql for more information.
<table>
<tabular ca="">
-type<colsep>This variable must be set by the underlaying DB_Sql-class!
-Currently mysql and oracle are supported.
-Q_Debug<colsep>true turns debugging on
+
+Q_Debug<colsep>true turns debugging within Query on. This is
+different to $_Debug, which turns on debugging within DB_Sql!
+
<rowsep>
-Q_Debug_print<colsep>A string which describes how to embed the debug-output,
-example <tt/ var $Q_Debug_print="\n<!-- QDebug: %s -->\n";/
+
+Q_Debug_print<colsep>A string which describes how to embed
+the debug-output, example <tt/ var $Q_Debug_print="\n<!-- QDebug: %s -->\n";/
<rowsep>
-meta_cache_off<colsep>This is for turning on or off the
-use of a cached metadata()-function.
+meta_cache_off<colsep>This is for turning on or off the use of
+caching the output of the metadata()-function. This is thought only for the
+case, that you have an application, which will ALTER TABLEs during runtime.
+
<rowsep>
+
Quoting<colsep>
-0 - turn quoting off,
+<tt/0/ - turn quoting off, this is good if you use the PHP-option
+<tt/magig_quotes_gpc/,
-1 - normal Quoting, using <tt/AddSlashes()/,
+<tt/1/ - normal Quoting, using <tt/AddSlashes()/,
+<tt/2/ - Replace \' into '' - this is needed e.g. for Sybase or Oracle.
-2 - Replace \' into '' - this is needed e.g. for Sybase or Oracle
+ It is planned to put this functionality into the DB_Sql-classes, cause
+correct quoting of the DBMS is a base functionality of DB_Sql.
-It is planned to put this var for the default value into the
-db_*-files.
<rowsep>
Quotechar<colsep>The char which a string is encapsulated with, default is '
+
<rowsep>
StrLengTrunc<colsep>This option will enforce to truncate all strings
to the maximum length of the table-field - good for Oracle and other DBs
-which will fail with longer strings. With this option you get a small
+which will fail with longer strings. With this option you get the
feeling of mySQL. :-)
+
<rowsep>
StrLengWarn<colsep>This will print a warning, if the string should or will be
-truncated. This can be used for debugging.
+truncated (see StrLengTrunc what will be done). This can be used for debugging.
+
+<rowsep>
+EmptyStringIsNull<colsep>Adds the behavior to Query, that an empty string
+is converted to NULL. This goes around a feature (I call this a bug)
+of Oracle, that you cannot always select what you have inserted.
+Be aware: Unset values within PHP will arrange Queries that dosn't
+include this value and not will set this value to NULL!
+
+<rowsep>
+NULLIsSpace<colsep>This is a fine feature for SAP and other applications,
+which store NULL always as a single space. It's a good idea to
+use this always together with EmptyStringIsNull.
+
+<rowsep>
+fireball_exclude_ereg<colsep>This is a regular expression-string for
+the function <tt/fireball_Clause()/. Please refer to this we will explain it
+there.
+
+<rowsep>
+fireball_replace_char<colsep>This is an SQL-char for the LIKE-operator.
+Meaningful values are '_' and '%'.
+
</tabular>
-<caption>Accessible instance variables.</caption>
+<!-- I dont understand why there is an error... -->
</table>
+
+<sect2>Accessible instance variables: currently none
+<p>
+Currently none?
+
+
+
+
<sect2>Instance methods
<p>
+
<sect3>Accessible instance methods
<p>
<descrip>
-<tag>sql2phptype($type,$format='')</tag>
-<p>
-This function gets a datatype form the DB (taken from metadata) and returns
-a more or less equivalent php-datatype.
-
-<tag>convert($val,$meta,$special="")</tag>
-<p>
-This function converts the value $val depending on type $meta to a
-correspondending SQL-type.
+<tag>insert_Clause ($table,$fields,$special='',$params="soft")</tag>
+<p>Function to generate an insert-clause.
<descrip>
- <tag>val</tag>
- <p> - the value.
- There is a special case: If value is "NULL" and
- the type is not "string" or subtype is empty, then
- a value "NULL" is inserted. This let you just spare
- a little bit work with $special
+ <tag>(string) $table</tag>
+ The name of the table or view
- <tag>meta</tag>
- <p> the meta information for this field (that's what
- is returned by metadata() from DB_sql-class, but just one
- single row, e.g. $meta[2], not hole $meta!).
+ <tag>(assoc.array) $fields</tag>
+ is an assoc. array consisting out of <tt/table_name => value-pairs/
- <tag>$special</tag>
- <p>Overwrites the type of the var if set. Some special
- meanings:
+ <tag>(assoc.array) $special</tag>
+ commit special handling to convert() (See general notes)
- "NULL" means, that this value must be set to "NULL" (overriding any $val)
+ <tag>(assoc.array or string) $params</tag>
+ currently not used.
- "func" means, that $val should be untouched -
- e.g. to insert the value of a SQL-function
- <tt/INSERT INTO bla VALUES ( time=NOW() ) /
+ A possible plan for the parameter "check" could be, that
+ strong will check, if all of the associative fields you have given
+ with $field, will be used.
+
+ <tag>returns (string)</tag>
+ Returns an insert clause or false. It's then on you to modify it and
+send it to your Database.
</descrip>
+
+Some extra notes: unset values will not produce an entry. Most
+SQL-DB-Servers interprets this as NULL value, but others will complain, that
+it is an uncomplete insert and not all values are set. In this case it is a
+good idea to use insert_plain_Clause().
-<tag>insert_plain_Clause($table,$fields,$special,$check="soft")</tag>
+Values in $fields which are set, but dosn't exist in the
+corresponding table won't produce an entry for insert.
+
+
+<tag>insert_plain_Clause($table,$fields,$special='',$check="soft")</tag>
<p> Function to generate a plain INSERT-Clause
("plain" means, that every field in the table will
be set to a value, default is '' or 0 if nothing said
- in $special). It returns the insert clause. It's on you to modify
-
+ in $special).
+
+Works like insert_clause() (indeed it calls it inside) with the difference,
+that it will set ALL values of a row to a value, no matter if the
+corresponding associative PHP-array has an unset-value or not.
<descrip>
- <tag>$table</tag>
+ <tag>(string) $table</tag>
<p>The name of the table or view
- <tag>$fields</tag>
+ <tag>(assoc.array) $fields</tag>
<p> is an assoc. Array consisting out of
table_name => value-pairs
- <tag>$special</tag>
+ <tag>(assoc.array) $special</tag>
<p> is an assoc. field which will commit special
handling to convert() (See there)
- <tag>$check</tag>
- <p> could be "strong" or "soft".
- "soft" won't tell you if there were to less
- or too much fields (good for debuging)
- </descrip>
+ <tag>(assoc.array or string) $params</tag>
+ <p> Associative Array or string. If it is a string it is converted
+into the associative array "check".
+ <descrip>
+<tag>check => strong | soft (default)</tag>
+
+'strong' tells you if there were to less or too much fields (good for
+debuging)
+
+<tag>nullisnull => true</tag>
+instead of inserting '' or 0 if the field is not set (unset)
+it will write NULL if you don't want either this or the other use
+insert_Clause(). This is only nearly the same as the behavior of the normal
+insert_Clause(), cause it will generate an explizite insert of the value
+NULL for the insert query instead of not mention it like insert_Clause().
+
+ </descrip>
+ <tag>returns (string)</tag>
+ Returns an insert clause or false. It's then on you to modify it and
+send it to your Database.
-<tag>replace_plain_Clause ($table,$fields,$special,$check="soft")</tag>
-<p>Produces a special mySQL-clause. See <tt/insert_plain_Clause()/ for the
-arguments.
+ </descrip>
-<tag> update_plain_Clause($table,$fields,$special,$where,$check="soft")</tag>
-<p>This function is nearly the same, as insert_plain_Clause.
+<tag> update_Clause
+($table,$fields,$special_or_where='',$where_or_special='',$params='soft')</tag>
+<p>This function creates an update_Clause. The paramters should be known
+from the general descriptions and from the examples before. But there are
+some specialities:
<descrip>
- <tag>$where</tag>
- <p>this parameter is new and should be generated by yourself!
- <tag>$check</tag>
- knows 3 values: strong, soft and weak
- weak enables you to sent a query without $where (enables you
- to update the hole table)
+ <tag>(string) $table</tag>
+ <p>The name of the table or view
+
+ <tag>(assoc.array) $fields</tag>
+ In the case, that you don't set ANY other value after fields, fields
+ is taken as an WHERE-Array. This means the assoc. Array of $fields
+ will be given to the function unique_where_Clause().
+ unique_where_Clause searches for unique identifyers in your table
+ and returns an where-clause, which match only the unique fields.
+ This makes it possible to make update clauses with only 2
+ parameters, which is a very comfortable thing!
+
+ <tag>(assoc.array or string) $special_or_where,$where_or_special</tag>
+ Cause $special is always an array and $where is always a string
+ Query can determine, whether you mean the special or where.
+
+ <tag>(assoc.array or string) $params</tag>
+ <p> Associative Array or string
+ <descrip>
+<tag>check => 'strong' | 'soft' (default) | 'weak'</tag>
+
+'weak' enables you to sent a query without any $where (enables you
+to update the hole table).
+
+'soft' is the default and in this mode if no $where is given, it is
+generated from the $fields array, see above.
+
+'strong' will return an error, if where is empty.
+ </descrip>
+
+ <tag>returns (string)</tag>
+ Returns an update clause or false. It's then on you to modify it and
+send it to your Database.
</descrip>
+
+<tag> update_plain_Clause
+($table,$fields,$special_or_where='',$where_or_special='',$params='soft')</tag>
+<p>Like insert_plain_Clause(), update_plain_clause() makes an update for
+every row in your table. If no value is given from $fields, '' or 0 is
+updated. To go arround this you can use nullisnull => true for $params.
-<bf/Some things about $where/: The $where part is standardized over the hole
-query-class. It dosn't matter, if you write
+Hum, for most reasons this function makes no sense. It's implemented mainly
+for completness.
-"WHERE hugo='bla'" "hugo='bla'" or " WHERE hugo='bla'"
+ <descrip>
+ <tag>(string) $table</tag>
+ <p>The name of the table or view
-It will always be convertet into " WHERE hugo='bla'"
+ <tag>(string) $fields</tag>
+ In the case, that you don't set ANY other value after fields, fields
+ is taken as an WHERE-Array. This means the assoc. Array of $fields
+ will be given to the function unique_where_Clause().
+ unique_where_Clause searches for unique identifyers in your table
+ and returns an where-clause, which match only the unique fields.
+ This makes it possible to make update clauses with only 2
+ parameters, which is a very comfortable thing!
+
+ <tag>(assoc.array or string) $special_or_where,$where_or_special</tag>
+ Cause $special is always an array and $where is always a string
+ Query can determine, whether you mean the special or where.
+
+ <tag>(assoc.array or string) $params</tag>
+ <p> Associative Array or string:
+ <descrip>
+<tag>check => 'strong' | 'soft' (default) | 'weak'</tag>
+'weak' enables you to sent a query without any $where (enables you
+to update the hole table).
+
+'soft' is the default and in this mode if no $where is given, it is
+generated from the $fields array, see above.
+
+'strong' will return an error, if where is empty.
+
+<tag>nullisnull => true</tag>
+instead of setting '' or 0 if the field is not set (unset)
+it will write NULL if you don't want either this or the other use
+update_Clause().
+ </descrip>
+
+ <tag>returns (string)</tag>
+ Returns an update clause or false. It's then on you to modify it and
+send it to your Database.
+ </descrip>
-<tag> update_Clause ($table,$fields,$special,$where,$check="soft")</tag>
-<p> This function is nearly the same, as <tt/update_plain_Clause()/.
-The <bf/main difference/ between <tt/update_Clause()/ and
-<tt/update_plain_Clause()/ is, that this function will not write updates for
-fields, that are not given in $fields (isset is false).
-<tag>delete_Clause ($table,$where,$check="soft")</tag>
+<tag>delete_Clause ($table,$where_or_wfields='',$params="soft")</tag>
<p>Creates a DELETE-Clause. It checks, if $where is not empty - this saves
your life, if you forget it.
+
+If you set $params[check]="weak", this check isn't done!
+
+ <descrip>
+ <tag>(string) $table</tag>
+ The name of the table or view
+
+ <tag>(assoc.array or string) $where_or_wfields</tag>
+In short words you can specify a string which holds a where-clause or an
+assoc array which describes an unique identifier.
+See <em/General notes, for WHERE as string or array/ for better explanation.
+
+ <tag>(assoc.array or string) $params</tag>
+ <p> Associative Array or string:
+ <descrip>
+<tag>check => 'soft' (default) | 'weak'</tag>
+'weak' enables you to make a delete clause without $where (enables you
+to delete the hole table).
+
+'soft' is the default and in this mode if no $where is given, false will
+be returned.
+ </descrip>
+
+ <tag>returns (string)</tag>
+ Returns an update clause or false. It's then on you to modify it and
+send it to your Database.
+ </descrip>
+
+
+<tag>where_Clause($table,$fields,$op='',$special='',
+$andor='AND',$where='',$params="soft")</tag>
+Full automatic creation of a WHERE-clause. This functions covers the most
+used form like
+<tscreen><code>
+WHERE a=1 AND b=2 AND c=3 AND d=4 ...
+</code></tscreen>
+
+But there can be made some exceptions with the parameters $op, $special and
+$andor.
+
+ <descrip>
+ <tag>(string) $table</tag>
+ <p>The name of the table or view
+
+ <tag>(assoc.array) $fields</tag>
+ <p> is an assoc. array consisting out of
+ <tt/table_name => value-pairs/
+
+ <tag>(assoc.array) $op</tag>
+ Is an Array consisting out of <tt/table_name => operator-pairs/
+ Operator could be everything, what SQL understands.
+
+ If the operator for this table-name is empty, the operator '=' is
+ taken by default. If the belonging value is NULL (return of
+ <tt/convert()/) the operator 'IS' is taken instead. Any other
+ operator than '=' is then replaced with 'IS NOT'. I thought this
+ makes sense for most cases.
+
+ <tag>(assoc.array) $special</tag>
+ <p> is an assoc. field which will commit special
+ handling to <tt/convert()/ (See there)
+
+ <tag>(string) $andor</tag>
+ Only two values makes sense here: 'AND' and 'OR', there is no
+ check for it. If no value or empty value is given, the default is
+ 'AND'.
+
+ <tag>(string) $where</tag>
+ This is a where-clause. It will be added with $andor at the end
+ of this generated clause. This is good if you need to make some
+ very special WHERE-part but the rest of the WHERE is simple standard.
+
+ <em/Note/: We mentioned it above: A WHERE-string can have the form
+ " WHERE blablabla" or just "blablabla". The leading "WHERE" is
+ removed. This means, that you can directly give the output of
+ another WHERE-funtion to this parameter.
+
+ <tag>(assoc.array or string) $params</tag>
+ <p> Associative Array or string:
+ <descrip>
+<tag>check => 'strong' | 'soft' (default) </tag>
+'strong' outputs currently just a warning that the result is empty.
+
+'soft' is the default. It's on you to check, wether <tt/where_Clause/
+returned true or false.
+ </descrip>
+
+ <tag>returns (string)</tag>
+ Returns an update clause or false. It's then on you to modify it and
+send it to your Database.
+ </descrip>
+
+
+<tag>unique_where_Clause($table,$fields,$op='',$special='',
+$andor='AND',$where='',$params="soft")</tag>
+This function is like <tt/where_Clause()/ (it is called inside) but with the
+difference, that a WHERE-clause is returned, that will only match for the
+primary key or other unique identifier(s) of the table.
+
+The function will return false, and print out warnings, if no unique
+identfier for your table is found.
+
+ <descrip>
+ <tag>(string) $table</tag>
+ <p>The name of the table or view
+
+ <tag>(assoc.array) $fields</tag>
+ <p> is an assoc. array consisting out of
+ <tt/table_name => value-pairs/
+
+ <tag>(assoc.array) $op</tag>
+ Is an Array consisting out of <tt/table_name => operator-pairs/
+ Operator could be everything, what SQL understands.
+
+ If the operator for this table-name is empty, the operator '=' is
+ taken by default. If the belonging value is NULL (return of
+ <tt/convert()/) the operator 'IS' is taken instead. Any other
+ operator than '=' is then replaced with 'IS NOT'. I thought this
+ makes sense for most cases.
+
+ <tag>(assoc.array) $special</tag>
+ <p> is an assoc. field which will commit special
+ handling to <tt/convert()/ (See there)
+
+ <tag>(string) $andor</tag>
+ Only two values makes sense here: 'AND' and 'OR', there is no
+ check for it. If no value or empty value is given, the default is
+ 'AND'.
+
+ <tag>(string) $where</tag>
+ This is a where-clause. It will be added with $andor at the end
+ of this generated clause. This is good if you need to make some
+ very special WHERE-part but the rest of the WHERE is simple standard.
+
+ <tag>(assoc.array or string) $params</tag>
+ <p> Associative Array or string: The value is just handled over to
+ <tt/where_Clause()/. Inside <tt/unique_where_clause()/ there is no
+ special meaning for it.
+ <descrip>
+<tag>check => 'strong' | 'soft' (default) </tag>
+'strong' outputs currently just an additional warning that the result is empty.
+
+'soft' is the default.
+
+<tag> removenull => true</tag>
+NULL values are ignored, cause a primary or unique identifier for a table,
+cannot be defined as a NULL value (this is only true for all databases I
+know, perhaps others will allow this?). This is not the default behavior,
+cause it makes sense. A <tt/SELECT * FROM bla WHERE blubb IS NULL/ will
+always return nothing for such a table, which is correct. This behaviour can
+be used for IU_Clause() to make very simple input-forms.
+
+Seting it to true will removes those parts. In the case there is no other
+identifier this will lead to an empty WHERE-clause, which will return an
+error.
+ </descrip>
+
+ <tag>returns (string)</tag>
+ Returns a WHERE-clause or false. It's then on you to modify it and
+send it to your Database.
+ </descrip>
+
+
+
+<tag>simp_where_Clause ($mywhere,$andor='AND',$where='',$check="soft")</tag>
+Create a simple WHERE-clause. This function is completly different to others
+cause it will not <tt/convert()/ the <tt/name => value/-pairs for any
+reason.
+
+This function will help you in creating WHERE-clauses that are not very
+standard, but very big or complicated, so you don't have to hassle with
+strings and only need to create an array step by step.
+
+ <descrip>
+ <tag>(array) $mywhere</tag>
+ An array of simple expressions, eg. "firstname='Alex'"
+
+ <tag>(string) $andor</tag>
+ The operator between the $mywhere's. 'AND' is default but could be
+ also any other string (e.g. 'OR').
+
+ <tag>(string) $where</tag>
+ This is a where-clause. It will be added with $andor at the end
+ of this generated clause. This is good if you need to make some
+ very special WHERE-part but the rest of the WHERE is simple standard.
+
+ <tag>(assoc.array or string) $params</tag>
+ <p> Associative Array or string:
+ <descrip>
+<tag>check => 'strong' | 'soft' (default) </tag>
+'strong' will call <tt/halt()/, if the produced WHERE-clause is empty.
+
+'soft' is the default.
+ </descrip>
+
+ <tag>returns (string)</tag>
+ Returns a WHERE-clause or false. It's then on you to modify it and
+send it to your Database.
+ </descrip>
+
+
+
+<tag>IU_Clause ($table,$fields,$special='',$params='soft')</tag>
+
+Create an INSERT or UPDATE query for an unique row in a
+table or view.
+
+This function returns inserts or update queries, dependig if the
+unique or primary key inside <tt/$fields/ was found in the table or not.
+
+<tt/IU_Clause()/ is mainly thought for cases, when you need to make a very
+primitive and simple formular to insert testing-data - just that it works
+for you.
+
+In this example, you have to insert the primary key <tt/adr_id/ by yourself.
+But we assume, that it is defined as auto_increment.
+
+The advancement is, that you could make this simple input-form stepwise
+better and better. This supports "extreme programming"-style,
+cause you can implement a functionality in a very short time, then show this
+first step your customer and then improve it (etc.). In the final version,
+IU_Clause() is perhaps replaced with differneciated calls to
+insert_Clause() and update_Clause(). Inbetween you spare a mass of time,
+cause the customer sees earlier in the project results and can test these
+results. At the end of the project this will lead to a more stable and
+practical orienated application.
-If you set $check to "weak", this check isn't done!
+Example:
-<tag>exists ($table,$name,$val)</tag>
-<p>This function checks wether in table $table a
-field $name is set with value $val:
+<tscreen><code>
+<?php
+
+require("db/mysql/db_sql.inc");
+require("query_sql.inc");
+
+class Query_Example extends Query {
+ var $Host = "localhost";
+ var $Database = "test";
+}
+$tabname="adress";
+
+if ($action='change') {
+ $db = new Query_Example;
+ $db->query(IU_Clause($tabname,$db->capture_vars($tabname)));
+}
+?>
+<HTML><BODY>
+<FORM ACTION="<?php echo $PHP_SELF ?>?action=change">
+<INPUT NAME="adr_id"> Fill in 'NULL' for a new record!<br>
+<INPUT NAME="first_name"><br>
+<INPUT NAME="last_name"><br>
+<INPUT NAME="adress"><br>
+<INPUT NAME="zipcode"><br>
+<INPUT NAME="city"><br>
+</FORM>
+</code></tscreen>
+
+<tt/IU_Clause()/ is mainly thought for cases, when you need to make a very
+primitive and simple formular to insert testing-data - just that it works
+for you.
+
+In this example, you have to insert the primary key <tt/adr_id/ by yourself.
+But we assume, that it is defined as auto_increment.
+
+The advancement is, that you could make this simple input-form stepwise
+better and better. This supports "extreme programming"-style,
+cause you can implement a functionality in a very short time, then show this
+first step your customer and then improve it (etc.). In the final version,
+IU_Clause() is perhaps replaced with differneciated calls to
+insert_Clause() and update_Clause(). Inbetween you spare a mass of time,
+cause the customer sees earlier in the project results and can test these
+results. At the end of the project this will lead to a more stable and
+practical orienated application.
+
+<em/IMPORTANT Note/: Cause it is currently not possible to create a Query-class
+inside the Query class ($classname is unknown) we must call the function
+<tt/query()/ inside this function. So this will overwrite a former result
+and the result before calling this function is not saved!
+
+ <descrip>
+ <tag>(string) $table</tag>
+ <p>The name of the table or view
+
+ <tag>(assoc.array) $fields</tag>
+ <p> is an assoc. array consisting out of
+ <tt/table_name => value-pairs/
-<tt/SELECT * FROM $table WHERE $name = $val/
+ <tag>(assoc.array) $special</tag>
+ <p> is an assoc. field which will commit special
+ handling to <tt/convert()/ (See there)
+
+ <tag>(assoc.array or string) $params</tag>
+ <p> Associative Array or string: Parameter <tt/check/ is just handled
+ over to <tt/insert_Clause()/ or <tt/update_Clause()/.
+ <descrip>
+<tag>check => 'strong' | 'soft' (default) </tag>
+'strong' outputs currently just an additional warning that the result is empty.
+
+'soft' is the default.
+
+<tag>forceinsert => true</tag>
+Sorry, this is painful for me, but I have forgotten why I introduced this
+switch. The functionality is simple to explain: An insert-clause is
+returned, even if the row is found in your table. This is nearly identical with
+directly calling <tt/insert_Clause()/ - so this parameter make no sense to
+me at the first view.
+ </descrip>
+
+ <tag>returns (string)</tag>
+ Returns either an INSERT- or an UPDATE-clause or false.
+ You can check this like follows:
+<tscreen><code>
+switch (substr($query=$db->IU_Clause('bla',$fields),0,1)) :
+ case 'I':
+ # insert
+ break;
+ case 'U':
+ # update
+ break;
+ default:
+ # error
+endswitch;
+</code></tscreen>
+
+ </descrip>
+
+
+
+
+<tag>exists ($table,$name_or_fields,$val='')</tag>
+<p>
+<bf/The next three functions/ <tt/exists()/, <tt/getrow()/ and <tt/getrow_where()/
+have been made for checking, if a row exists in a table or not. I'm not
+quite happy with their style and perhaps I will completly rewrite them,
+making them more general and matching more the internal data-model.
+
+This function checks wether in table $table a
+field $name is set with value $val. Internaly it creates an SELECT like:
+
+<tt/SELECT COUNT(*) FROM $table WHERE $name = $val/
+
+In case of $name_or_fields is an array, the parameter $val is not needed and
+it creates a WHERE-clause via <tt/where_Clause()/. So it dosn't support
+an assoc. array <tt/$special/ and also no <tt/$parameters/.
It returns the number of found matches or zero.
+<em/IMPORTANT Note/: The results from any former query will be overwritten!
+
+ <descrip>
+ <tag>(string) $table</tag>
+ <p>The name of the table or view
+
+ <tag>(assoc.array or string) $name_or_fields</tag>
+ <p> is an assoc. array consisting out of
+ <tt/table_name => value-pairs/ or a name of a row of your table.
+
+ <tag>(string) $val</tag>
+ If $name_or_fields is a string, this must be set also.
+ </descrip>
+
+
+
<tag>getrow ($table,$name,$val)</tag>
-<p> This function creates a query like exists, but returns
- an assoc array of the first found row, or false if nothing found;
+<p> This function creates a query like <tt/exists()/, but returns
+ an assoc array of the first found row (instead of the numer of the found
+record) or false if nothing found;
field $name is set with value $val
-
-<tag>where_plain_Clause($mywhere,$andor='AND',$where='',$check="soft")</tag>
-<p> Let you generate a WHERE-Clause with a Loop.
-
-Returns a where-clause beginning with " WHERE "
-
- ## This function generates a where-clause
- ## $mywhere An array of simple expressions, eg. "firstname='Alex'"
- ## $andor This string is printed bewtween the where-Array
- ## default is 'AND'. It will handle an existing
- ## $oldwhere correctly. You can set this to '', but then
- ## the correct operator must be set by you in the where
- ## $where an existing WHERE-clause. Default is empty.
- ## $check if 'strong', it will stop, if an empty where-clause
- ## will be returned, to avoid "full" selects. Default is
-soft
+
+ <descrip>
+ <tag>(string) $table</tag>
+ <p>The name of the table or view
+
+ <tag>(string) $name</tag>
+ <p> A name of a row in your table, typically the primary-key-name
+
+ <tag>(string) $val</tag>
+ The value.
+ </descrip>
+
+
+<tag>getrow_where ($table,$where)</tag>
+<p> Like <tt/getrow()/, but instead of $name and $val, a WHERE-Clause should
+be placed here. This can be generated by <tt/where_Clause()/, any other
+function, which returns a WHERE-Clause or by yourself.
+
+
+<tag>capture_vars ($table)</tag>
+
+This function is very usefull, cause it reads the definitions of <tt/$table/
+and reads then the <tt/$GLOBALS[rowname]/ for every row in your table and
+assigns it to an assoc. array. Here is the core-functionality for better
+understandig:
+
+<tscreen><code>
+ if (isset($GLOBALS[$name])) {
+ $result[$name] = $GLOBALS[$name];
+ }
+</code></tscreen>
+
+[The values are not converted in any form - perhaps it could be a good idea
+to include such a mechanism?]
+
+That's all... but I think I must talk a little bit more about, <bf/why/ I
+have implemented this. The base of this function is laying back to october
+1998. I programmed a form and like everytime in that time I thought it could
+be a good idea to use value names of associative arrays. Here is some
+example code of the form:
+
+<tscreen><code>
+...
+<input type="test" name="form[first_name]"><br>
+<input type="test" name="form[last_name]"><br>
+<input type="test" name="form[address]"><br>
+...
+</code></tscreen>
+
+In my PHP-program I could then just use:
+
+<tscreen><code>
+$db->query(make_insert_clause("adresstable",$form));
+ ^ this was the "pre-Query" time, just some functions...
+</code></tscreen>
+cause after scanning the data from the form before, PHP will assign all
+variables to $form as associative array, so the step to bring the data
+into my function <tt/make_insert_clause()/ could be done very easy.
+
+Then I come to a big hole in developing: I need a Java-Script-function,
+which could modify a value in an input-field. Now I know this is possible -
+with a little bit workarround, but in october 98 I hadn't had any idea, how
+to do this.
+
+So I rolled back, thinking. And I came to the conclusion, that it is not
+only in this case but in general not a good idea to use this fine
+assoc-array-mechanism for every form. It is much better to send <bf/all/ the
+data as global data and also receive it as global data and taking this nice
+assoc-array thing only for very special things.
+
+Now, 1.5 years ago, I think this was a very good decision. Why?
+
+Last week I changed some lines in a program I programmed in the
+assoc-array-style (the time before I though this was a good idea). But
+3 weeks ago I had to change some things in the old code
+of the program that used the style of forms <bf/without/ assoc-array. It was
+really surprising for me, that the style without using assoc-arrays for
+forms was much easier to understand and so I finished my work faster, than
+for the program with assoc-arrays.
+
+
+<tag>dispose_vars($params='')</tag>
+This is the opposite function of <tt/capture_vars()/. The core of the
+function takes the variable <tt/$this->Record/ and globalizes the values to
+the corresponding global variables. It is logical implement this, but indeed
+I have taken over this function from db_usql.
+
+<em/Note:/ This will overwrite existing global values!
+
+ <descrip>
+ <tag>(assoc.array) $params</tag>
+ The only value for this function is <tt/to_upper=>true/
+
+ This will make all names uppercase. The default is lowercase (like
+ everywhere in PHPLIB).
+ </descrip>
+
+<em/Note:/ import_record_vars($params='') is an alias to
+<tt/dispose_vars(array(to_upper=>true))/ for compatibility to db_usql.
+
+<tag>dispose_next_record($params='')</tag>
+Calls <tt/dispose_vars()/ <em/after/ calling <tt/next_record()/.
+
+
+<tag>dispose_asoc_array($array,$params='')</tag>
+This function will do the same as <tt/dispose_vars()/ but it will not
+dispose <tt/$this->Record/, it will dispose an associcative array you
+have given. Think this mustn't explained further...
+
+
+
+<tag>all_changed_vars ($table,$fields,$where='',$check='soft')</tag>
+ This function returns an assoc. Array consisting out of
+<tt/name=>value-pairs/ which have a different value from the value
+currently existing in your table or view. This can be needed for different
+cases. For example you can make very time consuming checks only, when the
+corresponding value is changed by the user. Note that we used the words
+"time consuming", cause <tt/all_changed_vars()/ needs some time to calculate
+the differences.
+
+<em/BUGS/: Cannot handle NULL values correctly. Cannot handle an empty
+WHERE-clause. There are some TODO's!
+
+The function-call and other things in this function are old style. This
+function should be rewritten completly.
+
+ <descrip>
+ <tag>(string) $table</tag>
+ The name of the table or view
+
+ <tag>(assoc.array) $fields</tag>
+ is an assoc. array consisting out of <tt/table_name => value-pairs/
+
+ <tag>(string) $where</tag>
+ commit special handling to convert() (See general notes)
+
+ <tag>(string) $check</tag>
+ Outputs a warning if <tt/$check/ is not 'soft'.
+
+ <tag>returns (string)</tag>
+ Returns an associative array which constists out of those
+name=>value pairs, that will differ.
+ </descrip>
+
+
+<tag>copy_result($table,$translate='')</tag>
+<bf/ATTENTION: This function currently dosn't work correct! This is due to
+the fact, that the results of the former query will be overwritten after
+the first insert. So this function works only for the first record./
+
+This function can be used to "copy" all the records of a former
+query to another table you can hand over a translation-table,
+which is an assoc-array: this_query_column=>my_tablename_column
+renames this_query_column into my_table_column.
+
+<tt/dump_query($tablename,$bla='')/ is an alias to this function.
+
+
+<tag>fireball_Clause ($string,$query,$maxwords=0)</tag>
+
+This is great: A function which generates a search query from a single
+input-field (a simple string) like Fireball does (that why it is called
+fireball_Clause() -- of course there are many other searching engines, which
+use this format, but I like the name :-)
+
+ <descrip>
+ <tag>(string) $string</tag>
+ This is the searching string, it knows the following rules:
+ <descrip>
+ <tag>'word1 word2'</tag>
+ Result includes word1 OR word2
+
+ <tag>'+word1 +word2'</tag>
+ Result includes word1 AND word2
+
+ <tag>'-word'</tag>
+ Result dosn't include this word
+
+ <tag>'"fasel bla"' or 'fasel-bla'</tag>
+ Word is taken as a single word the punctuation is
+ replaced with '_' (configurable!)
+ </descrip>
+
+ANY of the combinations of rule 1-4 and any number of words (see
+$maxwords) are VALID!
+
+
+ <tag>(string) $query</tag>
+ This is a part of a WHERE-Clause, that should be generated.
+ It should look like the following:
+ <tscreen><code>
+ $query="( first_name like '%{s}%' or name like '%{s}%' or".
+ " street like '%{s}%' or zipcode like '{s}%' or".
+ " town like '%{s}%')"
+ </code></tscreen>
+ {s} is replaced by the current searching-word.
+ The query should (has to) be placed into brackets, cause otherwise
+ the like operators will match false.
+
+ <tag>$maxwords</tag>
+ Maximum number of searching words. Zero (default) will no check.
+ Too much words returns ARRAY(false,1);
+
+ <tag>return (array (string,string))</tag>
+ We will currently return an array with two values:
+ list($wherepart,$what) = fireball($x,$y);
+
+ <descrip>
+ <tag>$wherepart</tag>
+ is the part of the query which could be included to
+ the WHERE-Part of your Query.
+ We advise you, that a user can easily create queries
+ which are bigger than the maximum buffer-size of the
+ underlaying database; this has to be checked by yourself!
+
+ This result could be directly used as parameter $where
+ within the function where_Clause() or related functions
+
+ <tag>$what</tag>
+ Is a simplified form of the $part, which could be used for
+ other things, like informing the user about what he is
+ currently searching. It's on you to translate this into a more
+ understandable form.
+ </descrip>
+Example:
+<tscreen><code>
+list($wherepart,$what) = fireball_clause("hugo +bla -hugobla","(name='{s}')");
+echo "WHERE: $wherepart<br>WHAT: $what";
+
+Output:
+WHERE: ( (name='hugo') OR (name='bla') ) AND (name='bla') AND NOT (name='hugobla')
+WHAT: ( 'hugo' OR 'bla' ) AND 'bla' AND NOT 'hugobla'
+</code></tscreen>
+
+ </descrip>
+
+<em/Note/: See also the chapter "Instance variables". The variables
+<tt/$fireball_exclude_ereg/ and <tt/$fireball_replace_char/.
+
+
+
+</descrip>
+
+<sect3>Internal Instant Methods
+<p>
+
+<descrip>
+
+<tag>_QDebug($string)</tag>
+If $Q_Debug is set to true, ouputs a string which is formated with
+<tt/$Q_Debug_print/. This function cannot be called <tt/Q_Debug()/ (how I
+would like to, cause it is more logical) cause an instance in a class can
+only defined once.
+
+<tag>set_db_class($db_class)</tag>
+This is only a 3rd posibility for setting the classname. Not needed for
+anything. :-)
+
+<tag>sql2phptype($meta)</tag>
+This function converts a SQL datatype into a more or less equivalent
+php- (or Query) datatype by using a single subarray of the
+associative array which comes from metadata(). It returns an array of
+php_type and php_subtype. For example: The mySQL-datatype "DATETIME" is
+converted into the PHP-datatype "string"/"date". This datatype
+is then used inside of the function convert(). See below.
+
+<tag>convert($val,$meta,$special="")</tag>
+This function converts the value $val depending on type $meta back to a
+correspondending SQL-type.
+
+ <descrip>
+ <tag>val</tag>
+ - the value. Just a PHP variable you want to use inside of
+ a SQL-query.
+ There is a special case: If value is "NULL" and
+ the type is not "string" or subtype is empty, then
+ the value NULL is inserted. This lets you just spare
+ a little bit work with $special in some cases.
+
+ <tag>meta</tag>
+ like in sql2phptype()
+ the meta information for this field by using a single subarray of the
+ associative array which comes from metadata().
+ (e.g. $meta[2], not hole $meta!). This is used for sql2phptype().
+
+ <tag>$special</tag>
+ Overwrites the type of the var if set (makes by normal no sense).
+ Some special and very important meanings:
+
+ "NULL" means, that this value must be set to "NULL"
+ (overriding <em/any/ $val)
+
+ "func" means, that $val should be untouched -
+ e.g. to force the insertion of a SQL-function
+ <tt/INSERT INTO bla VALUES ( time=NOW() ) /
+
+ This list of special meanings can be expanded in future.
+ </descrip>
+
+Example:
+<tscreen><code>
+$meta=$db->metadata_buffered("auth_user");
+echo $db->convert("hugo",$meta[$meta[meta]['p_username']]);
+
+Output:
+'hugo'
+</code></tscreen>
+
+So this function can (and should be) used, for creating complicated own
+queries, which cannot be generated by Query itself.
+
+<tag>chkprms ($params)</tag>
+Internal function, which returns an array of splitted parameters.
+Many functions of Query have very special parameters, most of them
+influencing some checks. This function adjusts this parameter, that you
+could hand over the single parameter "check" as a string and
+only more than one parameter must be handed over as an associative array.
+
+
+<tag>special_or_where ($p1,$p2='')</tag>
+This function helps to decide if you have given a WHERE-parameter as
+string or as array. $p1 or $p2 is the special-array and $p2 or $p1 is a
+where-Parameter. Every possible situation is checked. It returns
+an array of ($special,$where).
+
+There are the following rules:
+<tscreen><code>
+A - Return nothing
+B - Return p1 as SPECIAL
+C - Return p1 as WHERE
+D - Return p2 as SPECIAL
+E - Return p2 as WHERE
+F - Return p1 as SPECIAL, p2 as WHERE
+G - Return p1 as WHERE, p2 as SPECIAL
+% - UNKNOWN / ERROR
+
+ | p1 is empty | p1 is array | p1 is string
+----------------------------------------------------------
+p2 is empty | A | B | C
+----------------------------------------------------------
+p2 is array | D | % | G
+----------------------------------------------------------
+p2 is string | E | F | %
+----------------------------------------------------------
+
+</code></tscreen>
+
+<tag>uniform_where ($where)</tag>
+brings the WHERE-clause (and any string) in the form
+" WHERE blablablabla"; which is used <em/everywhere/ in Query.
+
+<tag>uniform_vars (&$meta,&$fields,&$special)</tag>
+<p>Returns an array of associative arrays of
+values and (converted) names. This function is thought only for internal
+use, that's why it has call-by-reference parameters.
+(I think about using $special for renaming those names?)
+
+Example:
+<tscreen><code>
+$vals=array(p_user_id=md5(time()),p_username=>'hugo',p_password='blubb',p_perms='none');
+$meta=$db->metadata_buffered("auth_user");
+$special=ARRAY(); # only need, because of call by reference
+$returnval=$db->uniform_vars($meta,$fields,$special);
+
+$returnval is defined as follows:
+$returnval=Array(
+ Array("'7515b58f27006717a0c3363169a43bfb'","'hugo'","'blubb'","'none'"),
+ Array(p_user_id,p_username,p_password,p_perms)
+ );
+</code></tscreen>
+
+
+<tag>metadata_buffered($table)</tag>
+This function calls metadata() only if it won't find the class-internal
+buffer (the first time), or if you have turned buffering OFF. This speeds
+the Query-class strongly up, cause it is needed in many functions.
+
+
</descrip>
+
+
---------------------------------------------------------------------
To unsubscribe, e-mail: phplib-dev-unsubscribe <email protected>
For additional commands, e-mail: phplib-dev-help <email protected>
- Next message: ssilk: "[phplib-dev] cvs commit"
- Previous message: athompso: "[phplib-dev] cvs commit"
- Next in thread: ssilk: "[phplib-dev] cvs commit"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]