[v3 Feedback] Oudated documentation #168

Activity

1. kdambekalns

   added

   Zammad API Client v3

   on Oct 9, 2026
2. Kicknride commented on Oct 9, 2026

   

   Kicknride

   on Oct 9, 2026

   More actions

   Yes Claude IA saved me

   use ZammadAPIClient\ZammadClient;
   use ZammadAPIClient\Factory\GuzzleClientFactory;

   $factory = GuzzleClientFactory::withToken('API_URL', 'TOKEN');
   $client = new ZammadClient($factory);
3. kdambekalns commented on Oct 9, 2026

   

   kdambekalns

   on Oct 9, 2026

   Last edited by kdambekalns

   Author

   More actions

   Yes, finding the correct code is possible, but the documentation should be fixed anyway. 😇

   👍React with 👍2Reacted by Cyrille Hamel and DerPixler
4. derpixler

   self-assigned this

   on Oct 12, 2026
5. derpixler commented on Oct 12, 2026

   

   derpixler

   on Oct 12, 2026

   Contributor

   More actions

   Hi @kdambekalns, @Kicknride — thank you, both of you.

   You spent your own time for zammad between you the report was complete: one showed the documentation was wrong, the other posted what actually works so the next person wasn't stuck on it. That is considerably more than a bug report usually gives us. ❤️

   ---

   It is now fixed in #171, and I'd like your read on it before it goes in.

   You reported two things, and both turned out to be worth more than a doc patch.

   The withToken one went deeper than stale docs. You both independently reached for ZammadClient::withToken(), which told us something: the documented API was the one people expect, and the real one was awkward enough that nobody guessed it. So rather than only correcting the examples, the entry point changed to match:

   use ZammadAPIClient\Core\Auth;
   use ZammadAPIClient\ZammadClient;
   
   $client = ZammadClient::create('https://zammad.example', Auth::token('your-token'));

   @Kicknride — the form you posted still works unchanged, so nothing you wrote needs touching. 'GuzzleClientFactory::withToken()' is now deprecated in favour of the above and will go in 4.0. For what it's worth, that you got there by asking an AI to read the source rather than by reading our docs is the clearest verdict on them we've had.

   (00-connect.php is the whole setup now)

   Digging into it surfaced the cause. The Authorization header was set as a Guzzle client default header — a Guzzle feature, not something PSR-18 offers — so anything that wanted authentication had to go through GuzzleClientFactory. That is why the guide asked you to hand-write an AuthMiddleware for Symfony's client. The credential now goes to the RequestHandler, which composes every request whatever the transport, so any PSR-18 client authenticates the same way: 07-custom-http-client.php is the entire recipe. In docs/custom-http-client.md that section went from 41 lines to 15 — the decorator is still documented, but only for the one case that genuinely needs it: credentials that rotate at runtime.

   The CHANGELOG one was simply right. 3.0.0 still said "unreleased", 3.1.0 had no section at all. Both now carry their dates.

   While we were in there we also found that the README documented performOnBehalfOf() and setOnBehalfOfUser() — removed in 3.0.0 — and that docs/ imported a namespace that does not exist. Same failure mode as your report, different page.

   Two things we'd value your opinion on, and only these, because they are the two we cannot work out for ourselves:

   1. Does ZammadClient::create($url, Auth::token($token)) read like what you were looking for, or does it still take a detour?
   2. Was there anything else in the v3 docs that sent you the wrong way and that you worked around silently rather than reporting?

   Thanks for pushing on this — especially for the "the documentation should be fixed anyway" line. That is the reason this got looked at properly instead of being closed with a snippet.

   👍React with 👍1Reacted by Cyrille Hamel
6. derpixler

   removed

   Zammad API Client v3

   on Oct 12, 2026
7. kdambekalns commented on Oct 13, 2026

   

   kdambekalns

   on Oct 13, 2026

   Author

   More actions

   Thanks for the kind words and the fix. That goes above and beyond in itself, great!

   To answer your questions:

   1. ZammadClient::create($url, Auth::token($token)) is fine with me.
   2. I did not find the time to finish the upgrade yet, so there might still be things I'll come across. I'll let you know. 😎

   👍React with 👍1Reacted by Cyrille Hamel

   ❤️React with ❤️1Reacted by DerPixler
8. derpixler

   added a commit that references this issue on Oct 14, 2026

   Add Auth and ZammadClient::create(), fix outdated v3 docs (#168)

   ...

   b4d1fb8
9. derpixler commented on Oct 14, 2026

   

   derpixler

   on Oct 14, 2026

   Contributor

   More actions

   #171 is merged (db77427 on develop) and ships as 3.2.0 — not tagged yet.

   @Kicknride — one line of my earlier comment is wrong: "GuzzleClientFactory::withToken() is now deprecated in favour of the above and will go in 4.0." That notice was withdrawn before the merge. The helpers stay supported and nothing is scheduled for removal, so your snippet is fine as it is — create() is a recommendation for new code, not a migration you owe us.

   Links from my earlier comment point at the feature branch, so here they are on develop:

   • examples/cookbook/ — all recipes, each runnable on its own
   • 00-connect.php — the setup
   • 07-custom-http-client.php and docs/custom-http-client.md — your own PSR-18 transport
   • CHANGELOG 3.2.0 — everything else in the release

   Thanks again, both of you.

   👍React with 👍1Reacted by Cyrille Hamel
10. derpixler

    closed this as completedon Oct 14, 2026
11. derpixler

    added 2 commits that reference this issue on Oct 14, 2026

    Add Auth and ZammadClient::create(), fix outdated v3 docs (#168)

    ...

    06bd840

    Add Auth and ZammadClient::create(), fix outdated v3 docs (#168)

    ...

    6ea0633