Proposal: wp_get_archives_object() function

[anonymized_13665966]

I'm currently working on building a personal site using the WP REST API, and one of the features I want to introduce is an equivalent to the archives widget on the front-end.

Unfortunately, this isn't so straight forward given that I have no quick means of accessing an object representing the current archives. The existing function wp_get_archives() will return lots of lovely HTML - which I can use out of the box perfectly well - but this is useless given that I want full control of the data to manipulate/parse/sort as well as having something that is more suitable for output via JSON in the API.

I propose that a new function called wp_get_archives_object() be added to give developers immediate access to the archives object for general use without having to get their hands dirty.

As a compromise, perhaps add an additional parameter to wp_get_archives() that when set to true simply returns the object?

[pathartl]

Noticed this too. My major problem is that both wp_get_archives(), like wp_get_attachment_image() returns markup while functions like wp_get_current_user() or wp_get_theme() return objects. I don't think that an additional parameter to wp_get_archives() is the answer. How would the arguments translate into the object? If they don't, then what's the point of having arguments?

I think it'd be better to roll it into its own function. I think from a naming standpoint wp_get_archives() would return the object and wp_get_archives_list() would return the markup, but there's some obvious compatibility issues with that. So I guess what I'm saying is I'm +1 for breaking it off into it's own function.

All that being said, am I wrong in assuming that there's no preexisting archive object? Is this another thing to be taken into consideration?

[boonebgorges]

Hi davetgreen - Thanks for the ticket!

I agree 100% that there should be a separation of concerns here - wp_get_archives() has been a bugbear for me in the past, too. Whether it's a separate function or an 'echo' parameter for the existing function doesn't matter much to me.

Assuming you had a separate function - which, as pathartl notes, would have to be the one returning structured data, since we can't change the default behavior of wp_get_archives() - what exactly would it be returning? You say "the archives object", but I'm not sure what that means. Maybe it'd be a structured array of links? Something like:

array(
    [2015] => array(
        [09] => 'http://example.com/2015/09/',
        [11] => 'http://example.com/2015/11/',
    ),
    [2014] => array(
        // etc
    ),
)

Or do you have in mind an actual object, which would presumably have methods like get_years() and get_month( $year ), etc? (This is a neat idea, but not very WordPress-y.)

[anonymized_13665966]

I agree @pathartl there isn't much point leveraging the existing function: we're best introducing a brand new one. There isn't an object available already from what I've seen, so we'd need to construct this from scratch.

@boonebgorges The example you posted is along the lines of what I was thinking in terms of the data we need. Coming at this from a REST API angle, the output is going to be an array of objects, JSONified, so I would suggest that as a bare minimum we need the following properties: ID, type (month/year), title, slug and permalink.

For the month type perhaps add a parent property in each object? This might be overkill, but we could also have a count property for the number of posts in that archive.

Here's an example of what I'd be expecting:

  [
    {
    "id": 2,
    "title": "2015",
    "slug": "2015",
    "permalink": "http://www.domain.com/2015",
    "count": 300,
    "parent": null
    },
    {
    "id": 42,
    "title": "October",
    "slug": "2015/10",
    "permalink": "http://www.domain.com/2015/10",
    "count": 10,
    "parent": 2
    }
  ]

I think a discussion is worth having over methods like get_years() and get_months as these could be quite useful.

I'm happy to get involved in terms of coding this up. I've been looked for a way to make my first proper contribution to core so this may be the perfect opportunity. :)

[boonebgorges]

Let's take things one step at a time. A big WP_Archive API is probably overkill for such a specific application, since most (all?) of the business logic needed already lives in wp_get_archives().

We'll let the REST API handle the JSONification, but we can certainly return an array.

Your proposal of returning a flat array with 'parent' properties makes the process a bit easier from our point of view, but it puts the onus of building a tree onto the consumer of wp_get_archives(). If we're going to go that route - rather than returning a properly structured array, which would have multiple layers of hierarchy - it'd be nice to see a proof-of-concept of how the REST API or some other client would parse and use the data.

[pathartl]

From a REST API standpoint it seems kind of weird that the array would be built as a tree since no other endpoint does it (as far as I know). From a PHP theme standpoint it totally makes more sense to build it as a tree. It would be much easier to replicate the current wp_get_archives() as a tree.

For this, I'm a bit torn. Introducing a new schema to the REST API doesn't set a great precedent, but making it harder for developers isn't too nice either. Maybe some type of parameter for toggling the hierarchical output? Maybe the endpoint in the REST API automatically flattens it for us?

[boonebgorges]

Maybe some type of parameter for toggling the hierarchical output?

This seems right to me.

[anonymized_13665966]

Apologies for the delay in following up!

@boonebgorges @pathartl I think whilst my need for an archives object came about as a result of working with the REST API, I don't think we should be specifically catering for the RAPI itself. As long as the resulting object can be consumed via either PHP in the theme or via the RAPI without too much hassle then I think we should be ok.

So just to summarise, we're looking at creating a new function called something along the lines of wp_get_archives_object that returns an object containing a hierarchical array of objects containing the properties I mentioned earlier in the thread. The function also needs to have a $flat parameter that switches the output from hierarchical to flat.

Does that sound like a decent foundation for a patch moving forward? If so, I'd love to give this a shot this month.

[boonebgorges]

Replying to davetgreen:

Apologies for the delay in following up!

@boonebgorges @pathartl I think whilst my need for an archives object came about as a result of working with the REST API, I don't think we should be specifically catering for the RAPI itself. As long as the resulting object can be consumed via either PHP in the theme or via the RAPI without too much hassle then I think we should be ok.

So just to summarise, we're looking at creating a new function called something along the lines of wp_get_archives_object that returns an object containing a hierarchical array of objects containing the properties I mentioned earlier in the thread. The function also needs to have a $flat parameter that switches the output from hierarchical to flat.

Does that sound like a decent foundation for a patch moving forward? If so, I'd love to give this a shot this month.

Sure, this seems reasonable. If this is something you want to work on, please feel free to drop ideas and sketches in this ticket as you go - I can't think of anywhere in WP where we have anything quite like what we're describing here, which means you'll be designing something rather new. It may be nice to bounce around ideas about architecture and use before you have a merge-ready patch to present.

[anonymized_13665966]

@boonebgorges I'll update the ticket in the next 7-10 days with a rough outline, cheers!

This PR includes a few things:

1. Add new wp_get_archives_result_object() function that returns an array of archive links data. Example:

{{{php
$results = wp_get_archives_result_object();
print_r( $results );

Output
Array
(

[0] => stdClass Object

(

[url] => ​http://localhost:8889/2021/05/
[label] => May 2021
[post_count] => 1
[year] => 2021
[month] => 5

)

[1] => stdClass Object

(

[url] => ​http://localhost:8889/2021/04/
[label] => April 2021
[post_count] => 3
[year] => 2021
[month] => 4

)

[2] => stdClass Object

(

[url] => ​http://localhost:8889/2021/03/
[label] => March 2021
[post_count] => 2
[year] => 2021
[month] => 3

)

[3] => stdClass Object

(

[url] => ​http://localhost:8889/2021/02/
[label] => February 2021
[post_count] => 1
[year] => 2021
[month] => 2

)

[4] => stdClass Object

(

[url] => ​http://localhost:8889/2021/01/
[label] => January 2021
[post_count] => 5
[year] => 2021
[month] => 1

)

)
}}}

2. Introduces new wp_get_archives_result() which is used by both wp_get_archives() and wp_get_archives_result_object() for code reuse.
3. Refactor wp_get_archives().

Trac ticket: https://core.trac.wordpress.org/ticket/34058

[donmhico]

Hello @davetgreen,

This might be 6 years old late but thanks for the new feature request!

I've attached a PR that introduces a new method wp_get_archives_result_object() which returns an array of archive links data. This should should suffice the request.

Others are highly encouraged/needed to check and test.

[sabernhardt]

resetting milestone to Future Release