#2316 #2258 merge 2.x-posts-api -> 2.x-term-posts, resolve conflicts …

…manually

Favoring changes from 2.x-posts-api

docs/v1/getting-started/theming.md

@@ -7,7 +7,7 @@ title: "Theming"
 Let’s start with your single post. Find this file:
 
 ```
-wp-content/themes/{timber-starter-theme}/templates/single.twig
+wp-content/themes/{timber-starter-theme}/views/single.twig
 ```
 
 Brilliant! Open it up.

docs/v1/guides/acf-cookbook.md

@@ -24,7 +24,7 @@ You can retrieve an image from a custom field, then use it in a Twig template. T
 ### The quick way (for most situations)
 
 ```twig
-<img src="{{ Image(post.meta('hero_image')).src }}" />
+<img src="{{ get_image(post.meta('hero_image')).src }}" />
 ```
 
 ### The long way (for some special situations)
@@ -57,7 +57,7 @@ You can now use all the above functions to transform your custom images in the s
 
 ```twig
 {% for image in post.meta('gallery') %}
-    <img src="{{ Image(image) }}" />
+    <img src="{{ get_image(image) }}" />
 {% endfor %}
 ```
 
@@ -101,7 +101,7 @@ You can access repeater fields within twig files:
 		<div class="item">
 			<h4>{{ item.name }}</h4>
 			<h6>{{ item.info }}</h6>
-			<img src="{{ Image(item.picture).src }}" />
+			<img src="{{ get_image(item.picture).src }}" />
 		</div>
 	{% endfor %}
 </div>
@@ -157,8 +157,8 @@ Similar to repeaters, get the field by the name of the flexible content field:
 ```twig
 {% for media_item in post.meta('media_set') %}
 	{% if media_item.acf_fc_layout == 'image_set' %}
-		<img src="{{ Image(media_item.image).src }}" />
-		<p class="caption">{{ Image(media_item.image).caption }}</p>
+		<img src="{{ get_image(media_item.image).src }}" />
+		<p class="caption">{{ get_image(media_item.image).caption }}</p>
 		<aside class="notes">{{ media_item.notes }}</aside>
 	{% elseif media_item.acf_fc_layout == 'video_set' %}
 		<iframe width="560" height="315" src="http://www.youtube.com/embed/{{ media_item.youtube_id }}" frameborder="0" allowfullscreen></iframe>

docs/v2/getting-started/introduction.md

@@ -10,7 +10,7 @@ Let’s get familiar with some of the concepts of Timber and Twig.
 If you want to start from scratch, you can use the following command. Run it from the **wp-content/themes** folder of your WordPress installation.
 
 ```bash
-composer create-project timber/getting-started-theme getting-started-theme
+composer create-project timber/learn-timber-theme learn-timber-theme
 ```
 
 And now …

docs/v2/guides/cookbook-images.md

@@ -102,7 +102,9 @@ When setting up your custom fields you’ll want to save the `image_id` to the f
 ### The quick way (for most situations)
 
 ```twig
-<img src="{{ Image(post.hero_image).src }}" />
+{% set image = get_image(post.hero_image) %}
+
+<img src="{{ image.src }}" alt="{{ image.alt }}" />
 ```
 
 ### The long way (for some special situations)

docs/v2/integrations/advanced-custom-fields.md

@@ -65,7 +65,7 @@ You can retrieve an image from a custom field, then use it in a Twig template. T
 ### The quick way (for most situations)
 
 ```twig
-<img src="{{ Image(post.meta('hero_image')).src }}" />
+<img src="{{ get_image(post.meta('hero_image')).src }}" />
 ```
 
 ### The long way (for some special situations)
@@ -102,7 +102,7 @@ You can now use all the above functions to transform your custom images in the s
 
 ```twig
 {% for image in post.meta('gallery') %}
-    <img src="{{ Image(image) }}" />
+    <img src="{{ get_image(image) }}" />
 {% endfor %}
 ```
 
@@ -124,6 +124,19 @@ or
 
 * * *
 
+## Relationship field
+
+The post data returned from a relationship field will not contain the Timber methods needed for easy handling inside of your Twig file. To get these, you’ll need to convert them into proper `Timber\Post` objects using `get_posts()`:
+
+```twig
+{% for item in get_posts(post.relationship_field) %}
+   {{ item.title }}
+   {# Do something with item #}
+{% endfor %}
+```
+
+* * *
+
 ## Repeater Field
 
 You can access repeater fields within Twig files:
@@ -137,7 +150,7 @@ You can access repeater fields within Twig files:
         <div class="item">
             <h4>{{ item.name }}</h4>
             <h6>{{ item.info }}</h6>
-            <img src="{{ Image(item.picture).src }}" />
+            <img src="{{ get_image(item.picture).src }}" />
         </div>
     {% endfor %}
 </div>
@@ -193,8 +206,8 @@ Similar to repeaters, get the field by the name of the flexible content field:
 ```twig
 {% for media_item in post.meta('media_set') %}
     {% if media_item.acf_fc_layout == 'image_set' %}
-        <img src="{{ Image(media_item.image).src }}" />
-        <p class="caption">{{ Image(media_item.image).caption }}</p>
+        <img src="{{ get_image(media_item.image).src }}" />
+        <p class="caption">{{ get_image(media_item.image).caption }}</p>
         <aside class="notes">{{ media_item.notes }}</aside>
     {% elseif media_item.acf_fc_layout == 'video_set' %}
         <iframe width="560" height="315" src="http://www.youtube.com/embed/{{media_item.youtube_id}}" frameborder="0" allowfullscreen></iframe>
@@ -211,8 +224,8 @@ Similar to nested repeaters, you should only call the `meta` method once when yo
 {% for media_item in post.meta('media_set') %}
     {% if media_item.acf_fc_layout == 'image_set' %}
         {% for image_item in media_item.image_set %}
-            <img src="{{ Image(image_item.image).src }}" />
-            <p class="caption">{{ Image(image_item.image).caption }}</p>
+            <img src="{{ get_image(image_item.image).src }}" />
+            <p class="caption">{{ get_image(image_item.image).caption }}</p>
             <aside class="notes">{{ image_item.notes }}</aside>
         {% endfor %}
     {% endif %}
@@ -261,13 +274,13 @@ add_filter( 'timber/context', 'global_timber_context' );
 
 /**
  * Filters global context.
- * 
+ *
  * @param array $context An array of existing context variables.
  * @return mixed
  */
 function global_timber_context( $context ) {
     $context['options'] = get_fields( 'option' );
-    
+
     return $context;
 }
 ```

docs/v2/upgrade-guides/2.0.md

@@ -51,14 +51,6 @@ Namespaced class names were already introduced in Timber version 1.0. Up until n
 
 A special case is the class alias `Timber` for the `Timber\Timber` class. We decided to keep it, because it’s more convenient to write `Timber::render()` instead of `Timber\Timber::render()`.
 
-### Twig
-
-The same goes for Timber classes in Twig. We realized there’s no need to have a «Timber» prefix. We can directly use `Post`, `Image`, `Term` and `User`. The following functions are now deprecated:
-
-- `{{ TimberPost() }}` – use `{{ Post() }}` instead
-- `{{ TimberImage() }}` – use `{{ Image() }}` instead
-- `{{ TimberTerm() }}` – use `{{ Term() }}` instead
-- `{{ TimberUser() }}` – use `{{ User() }}` instead
 
 ### Twig classes
 
@@ -134,6 +126,31 @@ In short:
 
 ## Twig
 
+### Updated function names
+
+In Twig, you could use functions that were called the same as classes to convert objects or IDs of objects into Timber object. To have the same names as in Timber’s public API, we’ve added the following functions:
+
+- `{{ get_post() }}`
+- `{{ get_posts() }}`
+- `{{ get_attachment_by() }}`
+- `{{ get_term() }}`
+- `{{ get_terms() }}`
+- `{{ get_user() }}`
+- `{{ get_users() }}`
+- `{{ get_comment() }}`
+- `{{ get_comments() }}`
+
+The following functions are now deprecated:
+
+- `{{ TimberPost() }}` – use `{{ get_post() }}` or `{{ get_posts() }}` instead
+- `{{ Post() }}` – use `{{ get_post() }}` or `{{ get_posts() }}` instead
+- `{{ TimberTerm() }}` – use `{{ get_term() }}` or `{{ get_terms() }}` instead
+- `{{ Term() }}` – use `{{ get_term() }}` or `{{ get_terms() }}` instead
+- `{{ TimberImage() }}` – use `{{ get_post() }}`, `{{ get_posts() }}` or `{{ get_attachment_by() }}` instead
+- `{{ Image() }}` – use `{{ get_post() }}`, `{{ get_posts() }}`, or `{{ get_attachment_by() }}` instead
+- `{{ TimberUser() }}` – use `{{ get_user() }}` or `{{ get_users() }}` instead
+- `{{ User() }}` – use `{{ get_user() }}` or `{{ get_users() }}` instead
+
 ### Namespaced Twig locations
 
 You can now use namespaced Twig locations. Read more about this in the [Template Locations Guide](https://timber.github.io/docs/v2/guides/template-locations/#register-your-own-namespaces).
@@ -247,11 +264,11 @@ function my_function_with_args( $foo, $post ) {
 
 ## New Attachment class
 
-Up until now, there was only a representation for WordPress image attachments in Timber. With version 2.0, we introduce a new `Timber\Attachment` class that represents WordPress attachments – also the ones that might not necessarily be images, like PDF files.
+Up until now, there was only a representation for WordPress image attachments in Timber. With version 2.0, we introduce a new `Timber\Attachment` class that represents WordPress attachments – including the ones that might not necessarily be images, like PDF files.
 
-- The `Timber\Image` class now extends the `Timber\Attachment` class. All your code should already be compatible with this change. But in the future, you might want to use the new `Timber\Attachment` class if you work with an attachment that is not an image.
-- We’ve added new methods for `Timber\Attachment`. See the section below (@todo: Add anchor link)
-- We’ve added a new Twig function `Attachment()`. (@todo: Add link to documentation)
+- The `Timber\Image` class now extends the `Timber\Attachment` class. All your code should already be compatible with this change. But in the future, you could use the new `Timber\Attachment` class if you work with an attachment that is not an image.
+- We’ve added new methods for `Timber\Attachment`. See the [section below](https://timber.github.io/docs/v2/upgrade-guides/2.0/#new-functions).
+- To get attachments from attachment IDs in Twig, you can use `{{ get_post(attachment_id) }}`. Behind the curtains, Timber uses [Class Maps](@todo: Add link) to use the `Timber\Image` and `Timber\Attachment` classes for attachment posts. (@todo: Add link to documentation)
 
 ## Deprecated functions and variables
 
@@ -303,7 +320,7 @@ The following functions were **removed from the codebase**, either because they
 - `get_edit_url()` – use `link()` instead
 - `get_field()` - use `{{ post.meta('my_field_name') }}` instead
 - `get_format()` – use `{{ post.format }}` instead
-- `get_image()` – use `{{ Image(post.my_image) }}` instead
+- `get_image()` – use `{{ get_image(post.my_image) }}` instead
 - `get_link()` – use `{{ post.link }}` instead
 - `get_modified_author()` – use `{{ post.modified_author }}` instead
 - `get_modified_date()` – use `{{ post.modified_date }}` instead
@@ -372,6 +389,8 @@ The following functions were **removed from the codebase**, either because they
 - `context_global()` - Gets the global context.
 - `context_post()` - Gets post context for a singular template.
 - `context_posts()` - Gets posts context for an archive template.
+- `get_attachment_by()` – Gets an attachment by its URL or absolute file path.
+- `get_post_by()` – Gets a post by title or slug.
 
 **Timber\Post**
 

lib/Attachment.php

@@ -2,6 +2,8 @@
 
 namespace Timber;
 
+use Timber\Factory\PostFactory;
+
 /**
  * Class Attachment
  *
@@ -117,26 +119,6 @@ class Attachment extends Post implements CoreInterface {
 	 */
 	public $caption;
 
-	/**
-	 * Creates a new `Timber\Attachment` object.
-	 *
-	 * @api
-	 * @example
-	 * ```php
-	 * // You can pass it an ID number
-	 * $myImage = new Timber\Attachment(552);
-	 *
-	 * // Or send it a URL to an image
-	 * $myImage = new Timber\Attachment( 'http://google.com/logo.jpg' );
-	 * ```
-	 *
-	 * @param int|mixed $attachment An attachment ID, a `Timber\Post`, a `WP_Post` object, an ACF
-	 *                              image array, a path (absolute or relative) or an URL.
-	 */
-	public function __construct( $attachment ) {
-		$this->init( $attachment );
-	}
-
 	/**
 	 * Gets the src for an attachment.
 	 *
@@ -156,6 +138,7 @@ public function __toString() {
 	 * @param int|mixed $iid An attachment identifier.
 	 */
 	public function init( $iid = null ) {
+		// @todo simplify this whole init process
 		$iid = $this->determine_id( $iid );
 
 		/**
@@ -191,6 +174,8 @@ public function init( $iid = null ) {
 		if ( isset( $this->ID ) ) {
 			$this->id = $this->ID;
 		}
+
+		return $this;
 	}
 
 	/**
@@ -408,7 +393,7 @@ public function path() {
 	 * @api
 	 * @example
 	 * ```twig
-	 * <a href="{{ Attachment(post.meta('job_pdf')).src }}" download>
+	 * <a href="{{ get_attachment(post.meta('job_pdf')).src }}" download>
 	 * ```
 	 * ```html
 	 * <a href="http://example.org/wp-content/uploads/2015/08/job-ad-5noe2304i.pdf" download>
@@ -534,17 +519,32 @@ public function parent() {
 			return false;
 		}
 
-		return new $this->PostClass( $this->post_parent );
+		$factory = new PostFactory();
+
+		return $factory->from( $this->post_parent );
 	}
 
 	/**
-	 * Gets a PHP array with pathinfo() info from the file.
-	 *
-	 * @api
+	 * Get a PHP array with pathinfo() info from the file
 	 *
-	 * @return array Path info from the file.
+	 * @deprecated 2.0.0, use Attachment::pathinfo() instead
+	 * @return array
 	 */
 	public function get_pathinfo() {
-		return pathinfo( $this->file );
+		Helper::deprecated(
+			"{{ image.get_pathinfo }}",
+			"{{ image.pathinfo }}",
+			'2.0.0'
+		);
+		return PathHelper::pathinfo($this->file);
+	}
+
+	/**
+	 * Get a PHP array with pathinfo() info from the file
+	 *
+	 * @return array
+	 */
+	public function pathinfo() {
+		return PathHelper::pathinfo($this->file);
 	}
 }

lib/Core.php

@@ -117,7 +117,7 @@ public function __get( $field ) {
 	 * @example
 	 * ```php
 	 * $data = array( 'airplane' => '757-200', 'flight' => '5316' );
-	 * $post = new Timber\Post();
+	 * $post = Timber::get_post();
 	 * $post->import(data);
 	 *
 	 * echo $post->airplane; // 757-200