CWIS Developer Documentation
Item.php
Go to the documentation of this file.
1 <?PHP
2 #
3 # FILE: Item.php
4 #
5 # Part of the ScoutLib application support library
6 # Copyright 2016 Edward Almasy and Internet Scout Research Group
7 # http://scout.wisc.edu
8 #
9 
13 abstract class Item
14 {
15 
16  # ---- PUBLIC INTERFACE --------------------------------------------------
17 
19  const NO_ITEM = -2123456789;
20 
30  public function __construct($Id)
31  {
32  # set up database access values
33  $ClassName = get_class($this);
34  static::SetDatabaseAccessValues($ClassName);
35  $this->ItemIdColumnName = self::$ItemIdColumnNames[$ClassName];
36  $this->ItemNameColumnName = self::$ItemNameColumnNames[$ClassName];
37  $this->ItemTableName = self::$ItemTableNames[$ClassName];
38 
39  # normalize item ID
40  $this->Id = static::GetCanonicalId($Id);
41 
42  # load item info from database
43  $this->DB = new Database();
44  $this->DB->Query("SELECT * FROM `".$this->ItemTableName."`"
45  ." WHERE `".$this->ItemIdColumnName."` = "
46  .intval($this->Id));
47  $this->ValueCache = $this->DB->FetchRow();
48 
49  # error out if item not found in database
50  if ($this->ValueCache === FALSE)
51  {
52  throw new InvalidArgumentException("Attempt to load ".$ClassName
53  ." with unknown ID (".$Id.").");
54  }
55  }
56 
60  public function Destroy()
61  {
62  # delete item from database
63  $this->DB->Query("DELETE FROM `".$this->ItemTableName."`"
64  ." WHERE `".$this->ItemIdColumnName."` = ".intval($this->Id));
65  }
66 
72  public function Delete()
73  {
74  $this->Destroy();
75  }
76 
81  public function Id()
82  {
83  return $this->Id;
84  }
85 
91  public static function GetCanonicalId($Id)
92  {
93  return $Id;
94  }
95 
103  public function Name($NewValue = DB_NOVALUE)
104  {
105  $NameColumn = strlen($this->ItemNameColumnName)
106  ? $this->ItemNameColumnName
107  : "Name";
108  return $this->UpdateValue($NameColumn, $NewValue);
109  }
110 
117  public function DateCreated($NewValue = DB_NOVALUE)
118  {
119  return $this->UpdateDateValue("DateCreated", $NewValue);
120  }
121 
128  public function CreatedBy($NewValue = DB_NOVALUE)
129  {
130  return $this->UpdateValue("CreatedBy", $NewValue);
131  }
132 
139  public function DateLastModified($NewValue = DB_NOVALUE)
140  {
141  return $this->UpdateDateValue("DateLastModified", $NewValue);
142  }
143 
150  public function LastModifiedBy($NewValue = DB_NOVALUE)
151  {
152  return $this->UpdateValue("LastModifiedBy", $NewValue);
153  }
154 
162  public static function ItemExists($Id)
163  {
164  # check for NULL ID (usually used to indicate no value set)
165  if ($Id === NULL)
166  {
167  return FALSE;
168  }
169 
170  # if an object was passed in
171  if (is_object($Id))
172  {
173  # make sure that the object passed in matches our called
174  # class or something that descends from our called class
175  $CalledClassName = get_called_class();
176  $ObjClassName = get_class($Id);
177  if (!is_a($Id, $CalledClassName))
178  {
179  throw new Exception(
180  "Called ".$CalledClassName."::ItemExists "
181  ."on an object of type ".$ObjClassName
182  .", which is unrleated to ".$CalledClassName);
183  }
184 
185  # call the object's ItemExists method
186  # (we want to do this rather than just setting $ClassName
187  # and continuing so that we'll properly handle subclasses
188  # that override ItemExists)
189  return $ObjClassName::ItemExists($Id->Id());
190  }
191 
192  # set up database access values
193  $ClassName = get_called_class();
194  static::SetDatabaseAccessValues($ClassName);
195 
196  # build database query to check for item
197  $Query = "SELECT COUNT(*) AS ItemCount"
198  ." FROM ".self::$ItemTableNames[$ClassName]
199  ." WHERE ".self::$ItemIdColumnNames[$ClassName]." = ".intval($Id);
200 
201  # check for item and return result to caller
202  $DB = new Database();
203  $ItemCount = $DB->Query($Query, "ItemCount");
204  return ($ItemCount > 0) ? TRUE : FALSE;
205  }
206 
207 
208  # ---- PRIVATE INTERFACE -------------------------------------------------
209 
210  protected $DB;
211  protected $Id;
212  protected $ItemIdColumnName;
214  protected $ItemTableName;
215  protected $ValueCache = array();
216 
217  static protected $ItemIdColumnNames;
218  static protected $ItemNameColumnNames;
219  static protected $ItemTableNames;
220 
227  protected static function CreateWithValues($Values)
228  {
229  # set up database access values
230  $ClassName = get_called_class();
231  static::SetDatabaseAccessValues($ClassName);
232 
233  # set up query to add item to database
234  $Query = "INSERT INTO `".self::$ItemTableNames[$ClassName]."`";
235 
236  # add initial values to query if supplied
237  if (count($Values))
238  {
239  $Query .= " SET ";
240  foreach ($Values as $Column => $Value)
241  {
242  $Assignments[] = "`".$Column."` = '".addslashes($Value)."'";
243  }
244  $Query .= implode(", ", $Assignments);
245  }
246 
247  # add item to database
248  $DB = new Database();
249  $DB->Query($Query);
250 
251  # retrieve ID for newly-created item
252  $NewItemId = $DB->LastInsertId();
253 
254  # create item object
255  $NewItem = new $ClassName($NewItemId);
256 
257  # return new item object to caller
258  return $NewItem;
259  }
260 
267  static protected function SetDatabaseAccessValues($ClassName)
268  {
269  if (!isset(self::$ItemIdColumnNames[$ClassName]))
270  {
271  self::$ItemIdColumnNames[$ClassName] = $ClassName."Id";
272  self::$ItemNameColumnNames[$ClassName] = $ClassName."Name";
273  self::$ItemTableNames[$ClassName] = StdLib::Pluralize($ClassName);
274  }
275  }
276 
284  protected function UpdateValue($ColumnName, $NewValue = DB_NOVALUE)
285  {
286  return $this->DB->UpdateValue($this->ItemTableName, $ColumnName, $NewValue,
287  "`".$this->ItemIdColumnName."` = ".intval($this->Id),
288  $this->ValueCache);
289  }
290 
300  protected function UpdateDateValue($ColumnName, $NewValue = DB_NOVALUE)
301  {
302  if ($NewValue !== DB_NOVALUE)
303  {
304  $Date = new Date($NewValue);
305  $NewValue = $Date->FormattedForSql();
306  }
307  return $this->UpdateValue($ColumnName, $NewValue);
308  }
309 }
DateLastModified($NewValue=DB_NOVALUE)
Get/set when item was last modified.
Definition: Item.php:139
static $ItemIdColumnNames
Definition: Item.php:217
DateCreated($NewValue=DB_NOVALUE)
Get/set when item was created.
Definition: Item.php:117
Name($NewValue=DB_NOVALUE)
Get/set name of item.
Definition: Item.php:103
Id()
Get item ID.
Definition: Item.php:81
static CreateWithValues($Values)
Create a new item, using specified initial database values.
Definition: Item.php:227
UpdateValue($ColumnName, $NewValue=DB_NOVALUE)
Convenience function to supply parameters to Database::UpdateValue().
Definition: Item.php:284
SQL database abstraction object with smart query caching.
Definition: Database.php:22
CreatedBy($NewValue=DB_NOVALUE)
Get/set ID of user who created the item.
Definition: Item.php:128
static $ItemNameColumnNames
Definition: Item.php:218
$DB
Definition: Item.php:210
Delete()
Destroy item.
Definition: Item.php:72
LastModifiedBy($NewValue=DB_NOVALUE)
Get/set ID of user who last modified the item.
Definition: Item.php:150
static SetDatabaseAccessValues($ClassName)
Set the database access values (table name, ID column name, name column name) for specified class...
Definition: Item.php:267
static Pluralize($Word)
Pluralize an English word.
Definition: StdLib.php:162
Destroy()
Destroy item.
Definition: Item.php:60
Definition: Date.php:18
const NO_ITEM
ID value used to indicate no item.
Definition: Item.php:19
$ItemNameColumnName
Definition: Item.php:213
Common base class for persistent items store in database.
Definition: Item.php:13
const DB_NOVALUE
Definition: Database.php:1738
$ItemTableName
Definition: Item.php:214
$ValueCache
Definition: Item.php:215
__construct($Id)
Constructor, used to load existing items.
Definition: Item.php:30
$Id
Definition: Item.php:211
static ItemExists($Id)
Check whether an item exists with the specified ID.
Definition: Item.php:162
static $ItemTableNames
Definition: Item.php:219
$ItemIdColumnName
Definition: Item.php:212
UpdateDateValue($ColumnName, $NewValue=DB_NOVALUE)
Convenience function to supply parameters to Database::UpdateValue(), with preprocessing of new value...
Definition: Item.php:300
static GetCanonicalId($Id)
Normalize item ID to canonical form.
Definition: Item.php:91