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  # set up database access values
171  $ClassName = get_called_class();
172  static::SetDatabaseAccessValues($ClassName);
173 
174  # build database query to check for item
175  $Query = "SELECT COUNT(*) AS ItemCount"
176  ." FROM ".self::$ItemTableNames[$ClassName]
177  ." WHERE ".self::$ItemIdColumnNames[$ClassName]." = ".intval($Id);
178 
179  # check for item and return result to caller
180  $DB = new Database();
181  $ItemCount = $DB->Query($Query, "ItemCount");
182  return ($ItemCount > 0) ? TRUE : FALSE;
183  }
184 
185 
186  # ---- PRIVATE INTERFACE -------------------------------------------------
187 
188  protected $DB;
189  protected $Id;
190  protected $ItemIdColumnName;
192  protected $ItemTableName;
193  protected $ValueCache = array();
194 
195  static protected $ItemIdColumnNames;
196  static protected $ItemNameColumnNames;
197  static protected $ItemTableNames;
198 
205  protected static function CreateWithValues($Values)
206  {
207  # set up database access values
208  $ClassName = get_called_class();
209  static::SetDatabaseAccessValues($ClassName);
210 
211  # set up query to add item to database
212  $Query = "INSERT INTO `".self::$ItemTableNames[$ClassName]."`";
213 
214  # add initial values to query if supplied
215  if (count($Values))
216  {
217  $Query .= " SET ";
218  foreach ($Values as $Column => $Value)
219  {
220  $Assignments[] = "`".$Column."` = '".addslashes($Value)."'";
221  }
222  $Query .= implode(", ", $Assignments);
223  }
224 
225  # add item to database
226  $DB = new Database();
227  $DB->Query($Query);
228 
229  # retrieve ID for newly-created item
230  $NewItemId = $DB->LastInsertId();
231 
232  # create item object
233  $NewItem = new $ClassName($NewItemId);
234 
235  # return new item object to caller
236  return $NewItem;
237  }
238 
245  static protected function SetDatabaseAccessValues($ClassName)
246  {
247  if (!isset(self::$ItemIdColumnNames[$ClassName]))
248  {
249  self::$ItemIdColumnNames[$ClassName] = $ClassName."Id";
250  self::$ItemNameColumnNames[$ClassName] = $ClassName."Name";
251  self::$ItemTableNames[$ClassName] = StdLib::Pluralize($ClassName);
252  }
253  }
254 
262  protected function UpdateValue($ColumnName, $NewValue = DB_NOVALUE)
263  {
264  return $this->DB->UpdateValue($this->ItemTableName, $ColumnName, $NewValue,
265  "`".$this->ItemIdColumnName."` = ".intval($this->Id),
266  $this->ValueCache);
267  }
268 
278  protected function UpdateDateValue($ColumnName, $NewValue = DB_NOVALUE)
279  {
280  if ($NewValue !== DB_NOVALUE)
281  {
282  $Date = new Date($NewValue);
283  $NewValue = $Date->FormattedForSql();
284  }
285  return $this->UpdateValue($ColumnName, $NewValue);
286  }
287 }
DateLastModified($NewValue=DB_NOVALUE)
Get/set when item was last modified.
Definition: Item.php:139
static $ItemIdColumnNames
Definition: Item.php:195
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:205
UpdateValue($ColumnName, $NewValue=DB_NOVALUE)
Convenience function to supply parameters to Database::UpdateValue().
Definition: Item.php:262
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:196
$DB
Definition: Item.php:188
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:245
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:191
Common base class for persistent items store in database.
Definition: Item.php:13
const DB_NOVALUE
Definition: Database.php:1706
$ItemTableName
Definition: Item.php:192
$ValueCache
Definition: Item.php:193
__construct($Id)
Constructor, used to load existing items.
Definition: Item.php:30
$Id
Definition: Item.php:189
static ItemExists($Id)
Check whether an item exists with the specified ID.
Definition: Item.php:162
static $ItemTableNames
Definition: Item.php:197
$ItemIdColumnName
Definition: Item.php:190
UpdateDateValue($ColumnName, $NewValue=DB_NOVALUE)
Convenience function to supply parameters to Database::UpdateValue(), with preprocessing of new value...
Definition: Item.php:278
static GetCanonicalId($Id)
Normalize item ID to canonical form.
Definition: Item.php:91