Hanson/vbot: a PHP WeChat web protocol library, and what its README actually promises

What Hanson/vbot solves, and for whom

Hanson/vbot exists to let PHP code talk to WeChat through the web protocol instead of through an official vendor SDK. The README opens by labelling the project a WeChat web protocol, and adds that it is for learning and reference only. That sentence sets the audience: developers who want to see how a PHP client authenticates, holds a session and exchanges messages with WeChat's web endpoints, and who are comfortable reading source under src/ and bin/ rather than following a product manual.

The repository is tagged with php, robot, wechat and weixin, and the description lists a wide surface: personal WeChat, WeCom, WeCom bots, the iPad protocol, Channels download, aggregated chat, RPA, hooks, reverse engineering, bulk sending, auto-reply and API integration. The README itself is far narrower than that description. It documents installation, links to external documentation, and links to a hosted aggregated-chat product and an AI auto-reply trial. Anyone arriving from the description should read the README first and calibrate expectations downward.

How the library is put together

The top level of the repository is small: .gitignore, LICENSE, README.md, bin/, composer.json and src/. There is no separate docs directory, no test directory and no sample application directory at the top level. Documentation lives off-repository, at create.hanc.cc/vbot and at three Apifox sites the README links for personal WeChat, WeCom and Channels respectively.

That layout tells you where the working code is. src/ holds the library classes, bin/ holds executable entry points, and composer.json defines the package name and its autoloading. The README's environment requirements name three PHP extensions, which points at three concrete responsibilities: fileinfo for storing files, gd for rendering a login QR code in the console, and SimpleXML for parsing XML. XML parsing implies the message layer receives XML payloads from WeChat, which is consistent with the web protocol era of the platform.

The README does not describe the internal class structure, the session lifecycle, or how reconnection after a dropped session is handled. Those details are only available by reading src/ or the external documentation. Treat the README as a pointer, not a specification.

Install Hanson/vbot with Composer and log in once

The README's install section is short and assumes Composer familiarity, stating plainly that you should already know how to use it. The environment requirements are PHP 7.0 or later plus the fileinfo, gd and SimpleXML extensions. Add the package to a project with:

composer require hanson/vbot

Composer resolves hanson/vbot and writes it into your vendor directory with autoloading configured. The README gives no version constraint, so Composer will pick according to your project's stability settings; the release list on the repository shows 2.0.17 as the most recent tag, dated 2021-11-01.

Before running anything, the README issues one instruction in emphatic terms: the language setting of the WeChat account you run must be Simplified Chinese, otherwise unknown errors may appear. That is a hard precondition, not a suggestion, and it is the first thing to check when a login attempt behaves strangely.

The gd extension is required because the console shows the login QR code. The README does not print a runnable login script, so the exact entry point has to come from bin/ or from the external documentation at create.hanc.cc/vbot. What you should expect after a correct setup is a QR code rendered in the terminal, which you scan with the WeChat account whose language is set to Simplified Chinese.

The gap between the README's scope and the repository's description

The repository description advertises bulk sending, auto-reply, RPA, hooks, reverse engineering, Channels download, aggregated chat and API integration. The README does not document any of those as features of the library. It links to them as separate offerings: an aggregated-chat product at juhebot.com, an AI auto-reply trial that the README says connects to COZE or FASTGPT, and three sets of external protocol documentation.

This is the most important thing to understand before adopting Hanson/vbot. The open repository is the web-protocol client. The production protocols, the customisation work and the AI auto-reply service are commercial and documented elsewhere. A team that reads the description and expects bulk sending or Channels download to be available in the MIT package will be disappointed, and the README does not correct that impression beyond its opening line about learning and reference.

There is also a maintenance signal worth reading carefully. The repository is not archived, and its last push was on 2026-05-30. The most recent tagged release is 2.0.17 from 2021-11-01, with 2.0.16 from 2021-09-08 and 2.0.15 from 2020-01-17 before it. Commits and releases are therefore moving on very different clocks, and anyone pinning a version should know that the tag they pin is old.

Where Hanson/vbot is the wrong choice

The README answers this itself. It states that the project is a WeChat web protocol for learning and reference, and that if you need a stable and reliable production protocol or customisation, you should look at the linked personal WeChat and WeCom documentation. That is the project's own boundary, and it should be taken literally.

The second limitation is environmental. The Simplified Chinese language requirement is not a preference; the README says other settings may produce unknown errors. Any deployment where the operating account's language is fixed by someone else is fragile from the start.

Third, the PHP version floor is 7.0. That is a low bar, but it also means the code was written against an older PHP idiom, and the README says nothing about PHP 8 behaviour. The README is also silent on rate limits, on account risk, and on what happens when WeChat changes the web endpoints. For a protocol client, that last omission matters more than any feature list: the README does not document a compatibility policy or a rollback path.

Finally, the documentation is split across four external sites, none of them versioned alongside the source. When the library and the docs drift, the source in src/ is the only authority, and the README does not say which documentation revision corresponds to which release.

Alternatives and the difference in approach

The honest alternative named in the README is not another open source library; it is the hosted protocol documentation the README links for personal WeChat and WeCom, plus the WeCom bot route. The difference is architectural rather than cosmetic. Hanson/vbot is a client you run yourself against WeChat's web protocol, which means you own the session, the QR login, the XML parsing and the failure handling in your own PHP process. The hosted route is a service relationship: the protocol work, including the stability guarantees the README says the open project does not offer, sits with the provider.

For a developer whose goal is to read and modify the client, that trade is bad, because a hosted service gives you no source to study. For a team whose goal is a messaging feature that has to keep working, the trade runs the other way, and the README's own recommendation points at the hosted option.

Within the open source space, the practical alternative to a PHP web-protocol client is to use an official vendor API and accept its restrictions, which removes the protocol work entirely but also removes the capabilities a web-protocol client is chosen for. The README does not name a specific competing library, so no direct comparison can be made here without inventing one.

Licence, releases and the cost of staying current

Hanson/vbot is MIT licensed, with the LICENSE file at the repository root. MIT is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained. That is a statement about the licence text, not legal advice, and a project embedding the library in a commercial product should have its own counsel review the notice requirements and any obligations introduced by the surrounding WeChat terms of service.

The upgrade picture is unusual. Releases are sparse: 2.0.15 in January 2020, 2.0.16 in September 2021, 2.0.17 in November 2021. The last push to the repository was on 2026-05-30, so there is activity after the last tag. That combination means a version constraint on a tag gets you code from 2021, while tracking master gets you untagged work whose relationship to the external documentation is not stated anywhere in the README.

Budget for the documentation cost as well. With no docs in the repository, every upgrade requires reading src/ and cross-checking four external sites. The README gives no changelog, no migration notes and no deprecation policy, so the practical upgrade procedure is to read the diff.

Editorial conclusion

Adopt Hanson/vbot if you are studying how a PHP client drives the WeChat web protocol and you accept the README's own framing of it as a learning reference. Do not adopt it as the base of a commercial messaging product: the README directs production and customisation needs to the separate hosted documentation for personal WeChat, WeCom and Channels, and the most recent release listed on the repository is 2.0.17 from 2021-11-01. Before writing any code, verify three things in your own environment: that the WeChat account you intend to use has its language set to Simplified Chinese as the README requires, that the PHP fileinfo, gd and SimpleXML extensions are present, and that the current master branch still matches the documentation at create.hanc.cc/vbot, since the repository's last push was on 2026-05-30 while the last tagged release is years older.

Frequently asked questions

Official sources

1. Hanson/vbot on GitHub
2. License: MIT
3. Project website
4. README
5. Releases