8 * Copyright (c) 2009-2013 Nicholas J Humfrey. All rights reserved.
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions are met:
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 * 2. Redistributions in binary form must reproduce the above copyright notice,
15 * this list of conditions and the following disclaimer in the documentation
16 * and/or other materials provided with the distribution.
17 * 3. The name of the author 'Nicholas J Humfrey" may be used to endorse or
18 * promote products derived from this software without specific prior
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 * POSSIBILITY OF SUCH DAMAGE.
34 * @copyright Copyright (c) 2009-2013 Nicholas J Humfrey
35 * @license http://www.opensource.org/licenses/bsd-license.php
39 * Class that represents an RDF resource
42 * @copyright Copyright (c) 2009-2013 Nicholas J Humfrey
43 * @license http://www.opensource.org/licenses/bsd-license.php
45 class EasyRdf_Resource
47 /** The URI for this resource */
48 protected $uri = null;
50 /** The Graph that this resource belongs to */
51 protected $graph = null;
56 * * Please do not call new EasyRdf_Resource() directly *
58 * To create a new resource use the get method in a graph:
59 * $resource = $graph->resource('http://www.example.com/');
62 public function __construct($uri, $graph = null)
64 if (!is_string($uri) or $uri == null or $uri == '') {
65 throw new InvalidArgumentException(
66 "\$uri should be a string and cannot be null or empty"
72 # Check that $graph is an EasyRdf_Graph object
73 if (is_object($graph) and $graph instanceof EasyRdf_Graph) {
74 $this->graph = $graph;
75 } elseif (!is_null($graph)) {
76 throw new InvalidArgumentException(
77 "\$graph should be an EasyRdf_Graph object"
83 * Return the graph that this resource belongs to
85 * @return EasyRdf_Graph
87 public function getGraph()
92 /** Returns the URI for the resource.
94 * @return string URI of this resource.
96 public function getUri()
101 /** Check to see if a resource is a blank node.
103 * @return bool True if this resource is a blank node.
105 public function isBNode()
107 if (substr($this->uri, 0, 2) == '_:') {
114 /** Get the identifier for a blank node
116 * Returns null if the resource is not a blank node.
118 * @return string The identifer for the bnode
120 public function getBNodeId()
122 if (substr($this->uri, 0, 2) == '_:') {
123 return substr($this->uri, 2);
129 /** Get a the prefix of the namespace that this resource is part of
131 * This method will return null the resource isn't part of any
132 * registered namespace.
134 * @return string The namespace prefix of the resource (e.g. foaf)
136 public function prefix()
138 return EasyRdf_Namespace::prefixOfUri($this->uri);
141 /** Get a shortened version of the resources URI.
143 * This method will return the full URI if the resource isn't part of any
144 * registered namespace.
146 * @return string The shortened URI of this resource (e.g. foaf:name)
148 public function shorten()
150 return EasyRdf_Namespace::shorten($this->uri);
153 /** Gets the local name of the URI of this resource
155 * The local name is defined as the part of the URI string
156 * after the last occurrence of the '#', ':' or '/' character.
158 * @return string The local name
160 public function localName()
162 if (preg_match("|([^#:/]+)$|", $this->uri, $matches)) {
167 /** Parse the URI of the resource and return as a ParsedUri object
169 * @return EasyRdf_ParsedUri
171 public function parseUri()
173 return new EasyRdf_ParsedUri($this->uri);
176 /** Generates an HTML anchor tag, linking to this resource.
178 * If no text is given, then the URI also uses as the link text.
180 * @param string $text Text for the link.
181 * @param array $options Associative array of attributes for the anchor tag
182 * @return string The HTML link string
184 public function htmlLink($text = null, $options = array())
186 $options = array_merge(array('href' => $this->uri), $options);
187 if ($text === null) {
192 foreach ($options as $key => $value) {
193 if (!preg_match('/^[-\w]+$/', $key)) {
194 throw new InvalidArgumentException(
195 "\$options should use valid attribute names as keys"
199 $html .= " ".htmlspecialchars($key)."=\"".
200 htmlspecialchars($value)."\"";
202 $html .= ">".htmlspecialchars($text)."</a>";
207 /** Returns the properties of the resource as an RDF/PHP associative array
210 * array('type' => 'uri', 'value' => 'http://www.example.com/')
212 * @return array The properties of the resource
214 public function toRdfPhp()
216 if ($this->isBNode()) {
217 return array('type' => 'bnode', 'value' => $this->uri);
219 return array('type' => 'uri', 'value' => $this->uri);
223 /** Return pretty-print view of the resource
225 * @param string $format Either 'html' or 'text'
226 * @param string $color The colour of the text
229 public function dumpValue($format = 'html', $color = 'blue')
231 return EasyRdf_Utils::dumpResourceValue($this, $format, $color);
234 /** Magic method to return URI of resource when casted to string
236 * @return string The URI of the resource
238 public function __toString()
245 /** Throw can exception if the resource does not belong to a graph
248 protected function checkHasGraph()
251 throw new EasyRdf_Exception(
252 "EasyRdf_Resource is not part of a graph."
257 /** Perform a load (download of remote URI) of the resource into the graph
259 * The document type is optional but should be specified if it
260 * can't be guessed or got from the HTTP headers.
262 * @param string $format Optional format of the data (eg. rdfxml)
264 public function load($format = null)
266 $this->checkHasGraph();
267 return $this->graph->load($this->uri, $format);
270 /** Delete a property (or optionally just a specific value)
272 * @param string $property The name of the property (e.g. foaf:name)
273 * @param object $value The value to delete (null to delete all values)
276 public function delete($property, $value = null)
278 $this->checkHasGraph();
279 return $this->graph->delete($this->uri, $property, $value);
282 /** Add values to for a property of the resource
285 * $resource->add('prefix:property', 'value');
287 * @param mixed $property The property name
288 * @param mixed $value The value for the property
289 * @return integer The number of values added (1 or 0)
291 public function add($property, $value)
293 $this->checkHasGraph();
294 return $this->graph->add($this->uri, $property, $value);
297 /** Add a literal value as a property of the resource
299 * The value can either be a single value or an array of values.
302 * $resource->add('dc:title', 'Title of Page');
304 * @param mixed $property The property name
305 * @param mixed $values The value or values for the property
306 * @param string $lang The language of the literal
307 * @return integer The number of values added
309 public function addLiteral($property, $values, $lang = null)
311 $this->checkHasGraph();
312 return $this->graph->addLiteral($this->uri, $property, $values, $lang);
315 /** Add a resource as a property of the resource
318 * $bob->add('foaf:knows', 'http://example.com/alice');
320 * @param mixed $property The property name
321 * @param mixed $resource2 The resource to be the value of the property
322 * @return integer The number of values added (1 or 0)
324 public function addResource($property, $resource2)
326 $this->checkHasGraph();
327 return $this->graph->addResource($this->uri, $property, $resource2);
330 /** Set value for a property
332 * The new value(s) will replace the existing values for the property.
333 * The name of the property should be a string.
334 * If you set a property to null or an empty array, then the property
337 * @param string $property The name of the property (e.g. foaf:name)
338 * @param mixed $value The value for the property.
339 * @return integer The number of values added (1 or 0)
341 public function set($property, $value)
343 $this->checkHasGraph();
344 return $this->graph->set($this->uri, $property, $value);
347 /** Get a single value for a property
349 * If multiple values are set for a property then the value returned
352 * If $property is an array, then the first item in the array that matches
353 * a property that exists is returned.
355 * This method will return null if the property does not exist.
357 * @param string|array $property The name of the property (e.g. foaf:name)
358 * @param string $type The type of value to filter by (e.g. literal or resource)
359 * @param string $lang The language to filter by (e.g. en)
360 * @return mixed A value associated with the property
362 public function get($property, $type = null, $lang = null)
364 $this->checkHasGraph();
365 return $this->graph->get($this->uri, $property, $type, $lang);
368 /** Get a single literal value for a property of the resource
370 * If multiple values are set for a property then the value returned
373 * This method will return null if there is not literal value for the
376 * @param string|array $property The name of the property (e.g. foaf:name)
377 * @param string $lang The language to filter by (e.g. en)
378 * @return object EasyRdf_Literal Literal value associated with the property
380 public function getLiteral($property, $lang = null)
382 $this->checkHasGraph();
383 return $this->graph->get($this->uri, $property, 'literal', $lang);
386 /** Get a single resource value for a property of the resource
388 * If multiple values are set for a property then the value returned
391 * This method will return null if there is not resource for the
394 * @param string|array $property The name of the property (e.g. foaf:name)
395 * @return object EasyRdf_Resource Resource associated with the property
397 public function getResource($property)
399 $this->checkHasGraph();
400 return $this->graph->get($this->uri, $property, 'resource');
403 /** Get all values for a property
405 * This method will return an empty array if the property does not exist.
407 * @param string $property The name of the property (e.g. foaf:name)
408 * @param string $type The type of value to filter by (e.g. literal)
409 * @param string $lang The language to filter by (e.g. en)
410 * @return array An array of values associated with the property
412 public function all($property, $type = null, $lang = null)
414 $this->checkHasGraph();
415 return $this->graph->all($this->uri, $property, $type, $lang);
418 /** Get all literal values for a property of the resource
420 * This method will return an empty array if the resource does not
421 * has any literal values for that property.
423 * @param string $property The name of the property (e.g. foaf:name)
424 * @param string $lang The language to filter by (e.g. en)
425 * @return array An array of values associated with the property
427 public function allLiterals($property, $lang = null)
429 $this->checkHasGraph();
430 return $this->graph->all($this->uri, $property, 'literal', $lang);
433 /** Get all resources for a property of the resource
435 * This method will return an empty array if the resource does not
436 * has any resources for that property.
438 * @param string $property The name of the property (e.g. foaf:name)
439 * @return array An array of values associated with the property
441 public function allResources($property)
443 $this->checkHasGraph();
444 return $this->graph->all($this->uri, $property, 'resource');
447 /** Count the number of values for a property of a resource
449 * This method will return 0 if the property does not exist.
451 * @param string $property The name of the property (e.g. foaf:name)
452 * @param string $type The type of value to filter by (e.g. literal)
453 * @param string $lang The language to filter by (e.g. en)
454 * @return integer The number of values associated with the property
456 public function countValues($property, $type = null, $lang = null)
458 $this->checkHasGraph();
459 return $this->graph->countValues($this->uri, $property, $type, $lang);
462 /** Concatenate all values for a property into a string.
464 * The default is to join the values together with a space character.
465 * This method will return an empty string if the property does not exist.
467 * @param string $property The name of the property (e.g. foaf:name)
468 * @param string $glue The string to glue the values together with.
469 * @param string $lang The language to filter by (e.g. en)
470 * @return string Concatenation of all the values.
472 public function join($property, $glue = ' ', $lang = null)
474 $this->checkHasGraph();
475 return $this->graph->join($this->uri, $property, $glue, $lang);
478 /** Get a list of the full URIs for the properties of this resource.
480 * This method will return an empty array if the resource has no properties.
482 * @return array Array of full URIs
484 public function propertyUris()
486 $this->checkHasGraph();
487 return $this->graph->propertyUris($this->uri);
490 /** Get a list of all the shortened property names (qnames) for a resource.
492 * This method will return an empty array if the resource has no properties.
494 * @return array Array of shortened URIs
496 public function properties()
498 $this->checkHasGraph();
499 return $this->graph->properties($this->uri);
502 /** Get a list of the full URIs for the properties that point to this resource.
504 * @return array Array of full property URIs
506 public function reversePropertyUris()
508 $this->checkHasGraph();
509 return $this->graph->reversePropertyUris($this->uri);
512 /** Check to see if a property exists for this resource.
514 * This method will return true if the property exists.
515 * If the value parameter is given, then it will only return true
516 * if the value also exists for that property.
518 * @param string $property The name of the property (e.g. foaf:name)
519 * @param mixed $value An optional value of the property
520 * @return bool True if value the property exists.
522 public function hasProperty($property, $value = null)
524 $this->checkHasGraph();
525 return $this->graph->hasProperty($this->uri, $property, $value);
528 /** Get a list of types for a resource.
530 * The types will each be a shortened URI as a string.
531 * This method will return an empty array if the resource has no types.
533 * @return array All types assocated with the resource (e.g. foaf:Person)
535 public function types()
537 $this->checkHasGraph();
538 return $this->graph->types($this->uri);
541 /** Get a single type for a resource.
543 * The type will be a shortened URI as a string.
544 * If the resource has multiple types then the type returned
546 * This method will return null if the resource has no type.
548 * @return string A type assocated with the resource (e.g. foaf:Person)
550 public function type()
552 $this->checkHasGraph();
553 return $this->graph->type($this->uri);
556 /** Get a single type for a resource, as a resource.
558 * The type will be returned as an EasyRdf_Resource.
559 * If the resource has multiple types then the type returned
561 * This method will return null if the resource has no type.
563 * @return EasyRdf_Resource A type assocated with the resource.
565 public function typeAsResource()
567 $this->checkHasGraph();
568 return $this->graph->typeAsResource($this->uri);
572 * Get a list of types for a resource, as Resources.
574 * @return EasyRdf_Resource[]
575 * @throws EasyRdf_Exception
577 public function typesAsResources()
579 $this->checkHasGraph();
580 return $this->graph->typesAsResources($this->uri);
583 /** Check if a resource is of the specified type
585 * @param string $type The type to check (e.g. foaf:Person)
586 * @return boolean True if resource is of specified type.
588 public function isA($type)
590 $this->checkHasGraph();
591 return $this->graph->isA($this->uri, $type);
594 /** Add one or more rdf:type properties to the resource
596 * @param string $types One or more types to add (e.g. foaf:Person)
597 * @return integer The number of types added
599 public function addType($types)
601 $this->checkHasGraph();
602 return $this->graph->addType($this->uri, $types);
605 /** Change the rdf:type property for the resource
607 * Note that the PHP class of the resource will not change.
609 * @param string $type The new type (e.g. foaf:Person)
610 * @return integer The number of types added
612 public function setType($type)
614 $this->checkHasGraph();
615 return $this->graph->setType($this->uri, $type);
618 /** Get the primary topic of this resource.
620 * Returns null if no primary topic is available.
622 * @return EasyRdf_Resource The primary topic of this resource.
624 public function primaryTopic()
626 $this->checkHasGraph();
627 return $this->graph->primaryTopic($this->uri);
630 /** Get a human readable label for this resource
632 * This method will check a number of properties for the resource
633 * (in the order: skos:prefLabel, rdfs:label, foaf:name, dc:title)
634 * and return an approriate first that is available. If no label
635 * is available then it will return null.
637 * @return string A label for the resource.
639 public function label($lang = null)
641 $this->checkHasGraph();
642 return $this->graph->label($this->uri, $lang);
645 /** Return a human readable view of the resource and its properties
647 * This method is intended to be a debugging aid and will
648 * print a resource and its properties.
650 * @param string $format Either 'html' or 'text'
653 public function dump($format = 'html')
655 $this->checkHasGraph();
656 return $this->graph->dumpResource($this->uri, $format);
659 /** Magic method to get a property of a resource
661 * Note that only properties in the default namespace can be accessed in this way.
664 * $value = $resource->title;
666 * @see EasyRdf_Namespace::setDefault()
667 * @param string $name The name of the property
668 * @return string A single value for the named property
670 public function __get($name)
672 return $this->graph->get($this->uri, $name);
675 /** Magic method to set the value for a property of a resource
677 * Note that only properties in the default namespace can be accessed in this way.
680 * $resource->title = 'Title';
682 * @see EasyRdf_Namespace::setDefault()
683 * @param string $name The name of the property
684 * @param string $value The value for the property
686 public function __set($name, $value)
688 return $this->graph->set($this->uri, $name, $value);
691 /** Magic method to check if a property exists
693 * Note that only properties in the default namespace can be accessed in this way.
696 * if (isset($resource->title)) { blah(); }
698 * @see EasyRdf_Namespace::setDefault()
699 * @param string $name The name of the property
701 public function __isset($name)
703 return $this->graph->hasProperty($this->uri, $name);
706 /** Magic method to delete a property of the resource
708 * Note that only properties in the default namespace can be accessed in this way.
711 * unset($resource->title);
713 * @see EasyRdf_Namespace::setDefault()
714 * @param string $name The name of the property
716 public function __unset($name)
718 return $this->graph->delete($this->uri, $name);