Code:
<?php
class zcObserverJapaneseObserver extends base {
function __construct() {
$attachNotifier = array();
$attachNotifier[] = 'NOTIFY_HEADER_START_ACCOUNT_EDIT'; // included if want to observe the data and/or manipulate the data at that point.
$attachNotifier[] = 'NOTIFY_NICK_CHECK_FOR_EXISTING_EMAIL';
// ... Etc for each notifier that this particular Japanese Observer should "listen" for.
$this->attach($this, $attachNotifier);
// Set any other class related data that may be needed to pass between functions or otherwise be maintained to support the overall process when using this observer
}
// To support use of new functionality added and supported in ZC 1.5.3 and above "unique" observers formed by "camelizing" (Removing underscore
// and then capitalizing the first letter of the next word. At this time, PHP does not differentiate functions that use or don't use capitalization;
// however, it makes the text easier to read and maintaining such consistency is a good practice especially if in the future capitalization becomes
// necessary.
// This is the function that is called when the notifier is met in a ZC 1.5.3+ system and it is expected by attempting to access the notifier:
// NOTIFY_NICK_CHECK_FOR_EXISTING_EMAIL
// My recommendation when writing such code is to include the non-camelized notifier at/around the function that is written this way to make
// finding it's use easier.
// Also, I recommend adding pertinent information about how the notifier was "first" used in the base code so that if/when it changes the changes
// can further be handled/addressed. It has been known to change between ZC versions and tracking down why code isn't working can be
// a little harder because this code is not "visually" inline with the execution point.
function updateNotifyHeaderStartAccountEdit(&$callingClass, $notifier) { // Note, no other parameters are provided here because the notifier does not include any additional parameters. Others could be added for this style of function without default value as the base code will send data for each of the first 12 parameters.
// Perform whatever is desired/necessary when this point in the code is reached. If there is data desired to be obtained at this point
// (ie. if there are modifications before this notifier or between this notifier and the next that is to be "generated" or collected, then need to
// use 'global $variable;' where $variable is the item to be retrieved. If there is data such as $_POST, $_GET, $_SESSION, etc... that is to be
// used, then generally speaking that information should be available without the use of global; however, there are exceptions and sometimes it
// is necessary to use the $GLOBALS[] style code.)
// Note that any variable that is specifically identified to the class that has made the call (class could be the base class in this case) is
// accessible and modifiable by use of $callingClass->OBJECT_OR_FUNCTION_OR_VARIABLE_ETC.
// $notifier contains the name of the notifier that was used to get to this point which in a more "advanced" situation could be different by
// the code of one observer function calling the code of this observer function. The other observer function will have received the name of
// notifier that triggered it and then that notifier variable could be sent to this code. Within this code alternate action could be taken if the
// the notifier was not 'NOTIFY_NICK_CHECK_FOR_EXISTING_EMAIL' or it could be taken if it is a specific notifier, etc...
}
// This is the second notifier presented as an example. Note from the code at the top that the notifier has three parameters. The first parameter
// ($email_address) is provided as a "read-only" style parameter. This is the case for all notifiers even as far back as at least ZC 1.3.9 (I believe
// it was the case further back; however, it is discouraged to try to support anything pre-1.3.9 due to significant security concerns and even 1.3.9
// had its own issues.
// The second and third parameters are possible to be writeable parameters if the below function is also written to support making it/them
// writeable (&$variable). The base code as of ZC 1.5.3 supports having 9 total writeable parameters that follow the one readable only parameter. (10 total when considering the class variable at the beginning of the parameters below).
// ZC 1.5.3 and above will send an empty array for the read-only parameter and NULL value for all remaining parameters that were not included in
// the initial notifier. (ie. if a &$param3, &$param4, &$param5, etc.. were included in the below function, then each of those would be NULL)
// 'NOTIFY_NICK_CHECK_FOR_EXISTING_EMAIL'
function updateNotifyNickCheckForExistingEmail(&$notifierClass, $notifier, $observe_email_address, &$observe_nick_error, &$observe_nick) {
// Variable names used above beginning with observe_ were chosen to demonstrate that they can be so named. They could also be identified
// as the variable name that existed in the original code (ie. $email_address instead of $observe_email_address) Maintaining consistency between
// the original code and this observer can help mentally remember/understand what is being affected.
// Again global variables may be needed in this function such as 'global $db;' to support performing operations using $db such as a query.
// Further, depending on where the calling code is within the global space, typically unless the code is located or loaded within a function or a
// class then the code is in the global space and anything that is present there can be made present here.
// For example, passing the value $nick_error in this notifier is technically unnecessary as it could be accessed by use of 'global $nick_error;', but
// it is better programming form to include the things that are expected to be used or needed. It just wasn't required...
// So in here do whatever is desired to be done with the data. If the result of processing in this function were to need to advise of an error,
// then changing $observe_email_error to true would set $error = true back in the original code. Again, this is another reason that $nick_error
// did not need to be included because $error also could have been brought into this code using 'global $error;'. Regardless, there are some
// considerations to be made. Because a notifier is provided, it could be used by any code that wants to use it. This means that it is possible
// that another observer has set $nick_error to true by the time this code has been loaded. Therefore some consideration must be made about
// what to do if an existing $nick_error has occurred. Should any of the code in here be processed? Should it be processed regardless? Will the
// processing resolve any $nick_error that might have existed and require the status to be changed back to false?
// Basically getting to the concept that unless the issue that has set $nick_error to true is completely resolved within this code regardless of
// why it was set to true, $nick_error should not be returned or changed to false. Doing so could cause problems downstream in the code.
// Any changes made to $observe_nick will be carried over and back to the original code. Changes made to $observe_email_address will be "lost"
// when the code returns.
}
// With this particular calling file and there being so many notifiers within it, there may be data that exists at one notifier, that is needed to be
// used in another notifier section with it in the condition/state as originally provided. Meaning, it may be necessary to store a value in the class
// to be used later in processing or to replace something that had been set. Note that such "storage" is basically by session, so do not get
// yourself wrapped up in what is happening within the class because of someone else also navigating unless you are changing database settings
// or for some reason there is a need to account for all people doing something specific.
// Then there is the update() function which has existed since observers were generated (or thereabouts).
// The update() function in a pre-ZC 1.5.3 store only receives the first three parameters similar to the above function. It does not receive any of
// the remaining parameters. Therefore, the remaining parameters in a pre-ZC 1.5.3 store also will not have any default value assigned to them by
// ZC core code. This is important to recognize if this code could possibly be installed on a pre-ZC 1.5.3 store. Why? without a default value
// assigned, when the notifier is encountered (also assuming it exists in the "older" code), then the code/store will stop execution because the
// variables do not have an assignment (if a default assignment is not provided like below).
// The update() function in ZC 1.5.3 and above will for the first 12 parameters receive the value provided in the notifier or a value of NULL if the
// parameter is not provided. In this case, the code will execute fine if the below function does not have a default value assigned like what has
// been done. So the question becomes, why would the below update function code be provided/produced to cause a store to basically crash
// instead of to either silently not support this added functionality or actually support the operation?
// The other part about this function is that the update function is called in ZC 1.5.3 and above if the camelized function(s) like above are not
// found. So, as a point of note, if the code above is not executed, it may be that the function is "misspelt". The misspelling could be on purpose
// so that the code of the update function is called, or it could be by accident.
// Here is a format for the update() function that would support any version to date that has an observer system.
function update(&$callingClass, $notifier, $read_array, &$param1 = NULL, &$param2 = NULL, &$param3 = NULL, &$param4 = NULL, &$param5 = NULL, &$param6 = NULL, &$param7 = NULL, &$param8 = NULL, &$param9 = NULL) {
// So now that the update function has been called, because either the camelized notifier function doesn't exist or this software was installed on a
// pre-ZC 1.5.3 system, how does one proceed?
// Remember that the second parameter (called $notifier here) contains the notifier "name" such as 'NOTIFY_NICK_CHECK_FOR_EXISTING_EMAIL'.
// If wanted to execute specific code when that notifier has been executed/called then:
if ($notifier == 'NOTIFY_NICK_CHECK_FOR_EXISTING_EMAIL') {
// Perform the operation necessary for this notifier, which could include calling the above camelized observer function
// (updateNotifyNickCheckForExistingEmail) to contain/pass along the variables necessary.
// Again though, if this were a pre-ZC 1.5.3 system, then $param1 through $param9 would be NULL because of the above default values.
// Generally speaking this should be fine because the function should be able to know what to do if the values are NULL and handle the value(s)
// correctly or as necessary. Of course back on the discussion of what data was necessary and where the notifier is located, all of the
// associated data could be made global here and then basically passed to the above function(s). ie.:
global $email_address;
global $nick_error;
global $nick;
$this->updateNotifyNickCheckForExistingEmail($callingClass, $notifier, $email_address, $nick_error, $nick);
// The above will collect the three variables by the same name as they were in their original code, which does make them fully modifiable here;
// however, by expected process, the goal is/was not to modify $email_address otherwise it would have been passed as a modifiable variable.
// Those values will be sent to the applicable camelized update function, any saveable modifications made would be returned here, and then
// by the nature of the variables being global, those "saved" modifications would be made back to the base data.
// Some alternative operations/considerations could be made such as if $email_address is not NULL the assign the variable $email_address to
// whatever value is received with $read_array (All versions of ZC that support observers), $param1 would either be NULL (because pre-ZC
// 1.5.3 would not set anything to that or it would be the value that was sent to this observer (likely a false value) but in ZC 1.5.3+ only if the
// camelized function name doesn't exist. )
}
}
}
Bookmarks