universe is the list of knowable codes, tools, add-ons, integrations, etc for CiviCRM. The
- The standard CiviCRM git repositories (
- Any extensions registered on
civicrm.orgthat have a Git URL.
- Most infrastructure and supporting components behind
universe can help you analyze the technical state of the CiviCRM community's code. For example, suppose you want to change the
signature of a function in
getContactDetails(...). You can get a copy of the universe and search the entire
source tree for
getContactDetails to see how it's being used.
Use a fast network and fast storage device (SSD)
universe is fairly big. (At time of writing, ~2 GB.) A fast network will help with downloading, and a fast storage will help
Create the universe¶
If your system is configured to support civibuild, then simply run:
$ civibuild create universe
Alternatively, if you have a copy of
buildkit but don't use
civibuild, then run:
$ mkdir ~/src/universe $ fetch-universe ~/src/universe
Search the universe¶
Note the path to your copy (eg
cd to it.
$ cd ~/buildkit/build/universe
You can get a lot of information with standard Unix tools like
$ grep -r getContactDetails .
There's a lot you can do with
grep, such as:
# Case insensitive search $ grep -ri getContactDetails . # Ignore folders like `.git` or `.svn` $ grep -r --exclude-dir=.git --exclude-dir=.svn getContactDetails . # Edit all matching files $ vi $(grep -ril getContactDetails .)
Of course, there's nothing special about
grep here. Lots of other powerful tools will do the job, such as
ack or the Silver Searcher. The author of
published a longer list of relevant tools.
Why would you search
Continuing the example, you might argue, "
getContactDetails isn't officially an API, so it's fair-game to change whenever we want.
Searching the universe doesn't add anything."
In policy terms, that might be right... but is it really a safe change in practical terms? Most of the time... probably! But
some of the time, Murphy's Law kicks in -- changing
getContactDetails(...) might break 10 extensions. Arguably, the fault lies with
the extension author who called a non-API -- but that will bring little comfort to the 20 users who show up on StackExchange asking for
help, and it will still reflect badly on all of us.
universe is a simple way to get ahead of that risk -- and to make decisions based on empirical data rather than
What to do if searching
universe reveals a technical conflict?
universe is just a tool -- it's a way to get ahead of problems (by making them easier to discover). It's not an over-arching policy on
what to do if you find a conflict. Returning to our
- Maybe you should change the approach -- keep the signature of
getContactDetailsas-is, but change something else.
- Or maybe the extensions should be updated to match the new signature.
- Or maybe you should give a heads-up to the other affected developers.
We're not trying to pre-judge the solution here. Main advice: start from the assumption that this is a shared problem. Finding a solution is good for you, for the other developers, and for the users. Encourage others to view it the same way.
Update the universe¶
universe is ever-expanding -- eg projects are updated, and new projects are added. Generally, it's not important to be accurate
"up-to-the-minute". But you may want to update if your copy of the universe is more than a week or two old.
Simply note the path to your copy (eg
~/src/universe) and run
$ fetch-universe ~/buildkit/build/universe