/**
* Fetch (and create, if necessary) "Places/nearby" streams
* corresponding ot the given parameters.
* @method streams
* @static
* @param {string} $publisherId The publisherId of the category streams
* @param {double} $latitude The latitude of the coordinates near which to relate
* @param {double} $longitude The longitude of the coordinates near which to relate
* @param {array} $options The options to pass to the Streams::relate and Streams::create functions. Also can contain the following options:
* @param {boolean} [$options.forSubscribers] Set to true to return the streams that are relevant to subscribers instead of publishers, i.e. users who want to know when something relevant happens, rather than users who want to relate the streams they publish to categories.
* @param {array|double} [$options.miles] Override the default array of distances found in the config under Places/nearby/miles. If options.forSubscribers is true, however, this should be one of the entries from the array in Places/nearby/miles config.
* @param {callable} [$options.create] If set, this callback will be used to create streams when they don't already exist. It receives the $options array and should return a Streams_Stream object. If this option is set to null, new streams won't be created.
* @param {callable} [$options.transform="array_keys"] Can be used to override the function which takes the output of Places_Nearby::forPublishers, and this $options array, and returns the array of ($originalStreamName => $newStreamName) pairs.
* @param {array} [$streamNames=null] Optional reference to fill with the stream names
* @return {array|boolean} Returns the array of category streams
*/
static function streams($publisherId, $latitude, $longitude, $options = array(), &$streamNames = null)
{
$miles = Q::ifset($options, 'miles', null);
$nearby = empty($options['forSubscribers']) ? Places_Nearby::forPublishers($latitude, $longitude, $miles) : Places_Nearby::forSubscribers($latitude, $longitude, $miles);
if (!isset($fromPublisherId)) {
$fromPublisherId = Users::communityId();
}
if ($transform = Q::ifset($options, 'transform', null)) {
$create = Q::ifset($options, 'create', null);
$transformed = call_user_func($transform, $nearby, $options);
} else {
$transformed = array_keys($nearby);
$create = Q::ifset($options, 'create', array('Places_Nearby', '_create'));
}
$streams = Streams::fetch(null, $publisherId, $transformed);
if (!isset($streamNames)) {
$streamNames = array();
}
foreach ($nearby as $k => $info) {
$name = isset($transformed[$k]) ? $transformed[$k] : $k;
if (empty($streams[$name])) {
if (empty($create)) {
continue;
}
$params = compact('publisherId', 'latitude', 'longitude', 'fromPublisherId', 'fromStreamName', 'transformed', 'miles', 'nearby', 'name', 'info', 'streams');
$streams[$name] = call_user_func($create, $params, $options);
}
if (!in_array($name, $streamNames)) {
$streamNames[] = $name;
}
}
return $streams;
}
/**
* Call this function to relate a stream to category streams for things happening
* around the given location.
* @method relateTo
* @static
* @param {string} $publisherId The publisherId of the category streams
* @param {double} $latitude The latitude of the coordinates near which to relate
* @param {double} $longitude The longitude of the coordinates near which to relate
* @param {string} $fromPublisherId The publisherId of the stream to relate
* @param {string} $fromStreamName The name of the stream to relate
* @param {string} $relationType The type of the relation to add
* @param {array} $options The options to pass to the Streams::relate and Streams::create functions. Also can contain the following options:
* @param {array} [$options.miles] Override the default set of distances found in the config under Places/nearby/miles
* @param {callable} [$options.create] If set, this callback will be used to create streams when they don't already exist. It receives the $options array and should return a Streams_Stream object. Otherwise the category stream is skipped.
* @param {callable} [$options.transform="array_keys"] Can be used to override the function which takes the output of Places_Nearby::forPublishers, and this $options array, and returns the array of ($originalName => $newCategoryName) pairs.
* @return {array|boolean} Returns the array of category streams
*/
static function relateTo($publisherId, $latitude, $longitude, $fromPublisherId, $fromStreamName, $relationType, $options = array())
{
$miles = Q::ifset($options, 'miles', null);
$nearby = Places_Nearby::forPublishers($latitude, $longitude, $miles);
if (!isset($fromPublisherId)) {
$fromPublisherId = Q_Config::expect('Q', 'app');
}
if ($transform = Q::ifset($options, 'transform', null)) {
$create = Q::ifset($options, 'create', null);
$transformed = call_user_func($transform, $nearby, $options);
} else {
$transformed = array_keys($nearby);
$create = Q::ifset($options, 'create', array('Places_Nearby', '_create'));
}
$streams = Streams::fetch(null, $publisherId, $transformed);
foreach ($nearby as $k => $info) {
$name = isset($transformed[$k]) ? $transformed[$k] : $k;
if (empty($streams[$name])) {
if (empty($create)) {
continue;
}
$params = compact('publisherId', 'latitude', 'longitude', 'fromPublisherId', 'fromStreamName', 'relationType', 'transformed', 'miles', 'nearby', 'name', 'info', 'streams');
$streams[$name] = call_user_func($create, $params, $options);
}
$stream = $streams[$name];
Streams::relate(null, $stream->publisherId, $stream->name, $relationType, $fromPublisherId, $fromStreamName, $options);
}
return $streams;
}
