{"id":21398,"date":"2019-11-20T10:03:20","date_gmt":"2019-11-20T10:03:20","guid":{"rendered":"https:\/\/blog.jetbrains.com\/phpstorm\/?p=15064"},"modified":"2024-01-09T14:51:00","modified_gmt":"2024-01-09T13:51:00","slug":"http-client-in-phpstorm-overview","status":"publish","type":"phpstorm","link":"https:\/\/blog.jetbrains.com\/pt-br\/phpstorm\/2019\/11\/http-client-in-phpstorm-overview","title":{"rendered":"HTTP Client in PhpStorm Overview"},"content":{"rendered":"<p>When developing a web service, you would usually test it by sending all kinds of HTTP requests to it and examining what\u2019s returned. In PhpStorm, you can do this directly in the code editor.<\/p>\n<p>In this post, we\u2019ll use the <a href=\"https:\/\/github.com\/JetBrains\/phpstorm-http-client-tutorial\" target=\"_blank\" rel=\"noopener\">github.com\/JetBrains\/phpstorm-http-client-tutorial<\/a> example project to demonstrate. You can clone it and navigate through its commit history to get to the corresponding phase of this overview. For each phase, run <code>composer update<\/code> to install and update what\u2019s required, and then <code>composer start<\/code> to start the PHP web server.<\/p>\n<p><iframe loading=\"lazy\" width=\"560\" height=\"315\" src=\"https:\/\/www.youtube.com\/embed\/n8KCuKhDSZY\" frameborder=\"0\" allow=\"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen><\/iframe><\/p>\n<p><!--more--><\/p>\n<h3 id=\"looking_around\">Looking around<\/h3>\n<p>In PhpStorm, your HTTP requests are stored in regular files with a <code>.http<\/code> or <code>.rest<\/code> extension. Having created one, type the URL inside. For simple requests such as GET, this is enough, so you can press <em>Alt+Enter<\/em> and select <em>Run<\/em> to execute the request right away. The request is executed, and the response is displayed in the <em>Run<\/em> tool window.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-create_run_request.png\" data-gif-src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-create_run_request.gif\" class=\"alignnone size-medium wp-image-15067\" alt=\"create_run_request\" width=\"960\" \/><\/p>\n<p>An <code>.http<\/code> file can hold as many requests as you need. You can separate them by typing <code>###<\/code>. If you execute a request, PhpStorm will even add this separator automatically, saving you from the hassle of having to type it each time. Not only this but you can also cut down on typing and speed things up a little by using live templates. To view all the available templates, press <em>Cmd+J<\/em> (<em>Ctrl+J<\/em> on Windows). As an example, let\u2019s use \u201cgtr\u201d, which expands into a GET request skeleton:<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-create_run_gtr_request.png\" data-gif-src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-create_run_gtr_request.gif\" class=\"alignnone size-medium wp-image-15070\" alt=\"create_run_gtr_request\" width=\"960\" \/><\/p>\n<p>As soon as you run the request, PhpStorm automatically creates a temporary run configuration for it. Now, if you change something in your PHP code, you can press <em>Ctrl+R<\/em> (<em>Shift+F10<\/em> on Windows) to rerun this configuration and test the changes right away, without switching context.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-http_request_run_config.png\" class=\"alignnone wp-image-15072\" alt=\"http_request_run_config\" width=\"706\" \/><\/p>\n<p>Sometimes you may want to perform some ad-hoc testing: run a particular method and compare what\u2019s returned between requests. For this purpose, you can use Scratches. They behave like regular physical files, but are not meant to be stored inside the project.<\/p>\n<p>To get started, create a new <code>.http<\/code> scratch file, and compose your request inside. When you run it, the information on the received response will be added in the very same file, directly under the request. Run it again to get the link to the next response, and so on. Now, you can click the button in the editor gutter, and compare the received responses on the spot via the differences viewer.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-compare_scratches.png\" data-gif-src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-compare_scratches.gif\" class=\"alignnone size-medium wp-image-15074\" alt=\"compare_scratches\" width=\"960\" \/><\/p>\n<p>Scratch files are intended to be ditched as soon as they are not needed, but what if you like a particular request? Then you can keep it with the project: select <em>Refactor | Move<\/em> file and move it to a regular <code>.http<\/code> file. As with any other project files, you can now commit it to a VCS, share it with your team, and use it as a reference for testing or documenting your Web API.<\/p>\n<p>As a recap, click the <em>Open Log<\/em> link in the editor\u2019s top right-hand corner. Here, you can view the last 50 executed requests, rerun any of them, or open the response file in the editor.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-requests_history_upd.png\" class=\"alignnone wp-image-15088\" alt=\"requests_history_upd\" width=\"500\" \/><\/p>\n<h3 id=\"authorization_and_variables\">Authorization and Variables<\/h3>\n<p>If your web service requires authorization, you can access it by providing the <em>Authorization<\/em> header, the authentication method, and the required credentials in your HTTP requests. This way, however, your credentials become part of the request, and sharing them is probably not a good idea.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-request_with_credentials.png\" class=\"alignnone wp-image-15077\" alt=\"request_with_credentials\" width=\"805\" \/><\/p>\n<p>Here, environment variables come to the rescue: we can replace the desired values with variables and then put them in place as soon as the request runs. Inside the requests, variables are provided enclosed in double curly braces, like this: <code>{{MyVariable}}<\/code>.<\/p>\n<p>To have the possibility to target different servers, let\u2019s start by replacing the host with <code>{{HOST}}<\/code>; then, we\u2019ll replace the user and password values with <code>{{USER}}<\/code> and <code>{{PASSWORD}}<\/code>. This way, we\u2019ve turned these values into variables.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-request_with_variables.png\" class=\"alignnone wp-image-15078\" alt=\"request_with_variables\" width=\"804\" \/><\/p>\n<p>To define these variables, you need to create a new file and name it <code>http-client.env.json<\/code>. Inside the file, define the environment standing for a specific server, and a set of variables for it.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-env_json.png\" alt=\"env_json\" width=\"300\" class=\"alignnone size-full wp-image-15079\" \/><\/p>\n<p>Since the <code>http-client.env.json<\/code> file will be shared with the project, too, we can take it a step further, and isolate username and password. So let\u2019s create another file and name it <code>http-client.private.env.json<\/code>. <em>Private <\/em>is key here \u2013 this file is intended to hold sensitive data, and it even gets ignored by a VCS by default. Inside the file, we will replicate our environment, and then provide the username and password.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-private_env_json.png\" class=\"alignnone wp-image-15080\" alt=\"private_env_json\" width=\"390\" \/><\/p>\n<p>When we run the request, PhpStorm substitutes the variables with actual values. What\u2019s more, your teammates can reuse the same request, but tailor it to their environments.<\/p>\n<h3 id=\"scripting\">Scripting<\/h3>\n<p>In the HTTP client, you can see what the web service returned and can react to it programmatically.<\/p>\n<p>Let\u2019s consider this example: when we run the first request, our web service returns a JSON response. We can then compose a simple script that will modify it, so that we can send the modified data back to the server using the second POST request.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-get_post_requests.png\" class=\"alignnone wp-image-15083\" alt=\"get_post_requests\" width=\"400\" \/><\/p>\n<p>Response handler scripts are enclosed in <code>&gt; {% %}<\/code>, written in JavaScript, and executed as soon as a response is received.<\/p>\n<p>In our first script, we refer to the <code>response<\/code> object, which contains information about the received response, and then grab the response body JSON and modify its <em>New features<\/em> key\u2019s value. Next, we refer to the <code>client<\/code> object, which stores the session metadata until you restart PhpStorm, and save the modified response body to a new <code>myResponse<\/code> global environment variable.<\/p>\n<pre class=\"EnlighterJSRAW\" data-enlighter-language=\"js\" data-enlighter-title=\"\">\r\n&gt; {%\r\n  response.body[&quot;Stable release&quot;] = &quot;2019.3&quot;;\r\n  client.global.set(&quot;myResponse&quot;, JSON.stringify(response.body));\r\n%}\r\n<\/pre>\n<p>When we rerun the request, the response gets modified and saved. In the second POST request, which sends the JSON data to the server, we can now set the <code>myResponse<\/code> variable as the request body, and run it to store the data on the server.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-get_post_requests_variable.png\" class=\"alignnone wp-image-15084\" alt=\"get_post_requests_variable\" width=\"450\" \/><\/p>\n<p>You can now rerun the first GET request \u2013 and make sure it returns modified data.<\/p>\n<h3 id=\"testing\">Testing<\/h3>\n<p>While it worked out pretty well this time, imagine having more scripts with all kinds of response values, conditions, or logic attached \u2013 checking each of them manually will eventually become a burden. Let\u2019s make PhpStorm do it for us.<\/p>\n<p>We will enhance the script so that it includes the actual test. Here, we use the <em>test<\/em> method, inside which we provide the name of the test, and then \u2013 the function that runs the test. Inside the function, we use the <code>assert<\/code> method, which checks the value of the response body JSON key, and outputs an error message if the condition is not met. You are not limited to a single check, of course \u2013 notice that we also added a condition checking the response status.<\/p>\n<pre class=\"EnlighterJSRAW\" data-enlighter-language=\"js\" data-enlighter-title=\"\">\r\n&gt; {%\r\n  client.test(&quot;Version&quot;, function() {\r\n  client.assert(response.body[&quot;Stable release&quot;] === &quot;2019.3&quot;, &quot;Returned no info on the latest\r\nrelease&quot;);\r\n});\r\n\r\n  client.test(&quot;Status&quot;, function() {\r\n    client.assert(response.status === 200, &quot;Response status is not 200&quot;);\r\n  });\r\n%}\r\n<\/pre>\n<p>Now, when you run the request, PhpStorm will provide you with the tests\u2019 results on the dedicated <em>Tests<\/em> tab. Should anything go awry, the test will fail, but you will know exactly what went wrong and can fix it right away.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2019\/11\/phpstorm-tests_tab.png\" class=\"alignnone wp-image-15085\" alt=\"tests_tab\" width=\"540\" \/><\/p>\n<p>We hope that this post sheds some light on what\u2019s possible with the HTTP Client. See <a href=\"https:\/\/www.jetbrains.com\/help\/phpstorm\/http-client-in-product-code-editor.html\" target=\"_blank\" rel=\"noopener\">the HTTP Client docs<\/a> to learn more, and make sure to check out the PhpStorm blog from time to time to keep up with the latest features.<\/p>\n","protected":false},"author":745,"featured_media":21415,"comment_status":"open","ping_status":"open","template":"","categories":[808,907,2347,126],"tags":[915,2635,91,2592,792,661],"cross-post-tag":[],"acf":[],"_links":{"self":[{"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/phpstorm\/21398"}],"collection":[{"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/phpstorm"}],"about":[{"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/types\/phpstorm"}],"author":[{"embeddable":true,"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/users\/745"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/comments?post=21398"}],"version-history":[{"count":1,"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/phpstorm\/21398\/revisions"}],"predecessor-version":[{"id":431633,"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/phpstorm\/21398\/revisions\/431633"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/media\/21415"}],"wp:attachment":[{"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/media?parent=21398"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/categories?post=21398"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/tags?post=21398"},{"taxonomy":"cross-post-tag","embeddable":true,"href":"https:\/\/blog.jetbrains.com\/pt-br\/wp-json\/wp\/v2\/cross-post-tag?post=21398"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}